Integrate with card payments
Build and customize the card fields to align with your branding.
1. Add card payments module to your app
Add the CardPayments
package dependency for your app using Swift Package Manager or CocoaPods:
Swift Package Manager
- Open Xcode.
- Follow the guide to add package dependencies to your app.
- Enter
https://github.com/paypal/paypal-ios/
as the repository URL.
- Select the checkbox for the
CardPayments
framework.
CocoaPods
Include PayPal/CardPayments
in your Podfile:
1# Podfile
2pod 'PayPal/CardPayments'
2. Create CardClient
A CardClient
helps you attach a card to a payment.
In your iOS app:
- Use the
CLIENT_ID
to construct a CoreConfig
.
- Construct a
CardClient
using your CoreConfig
object.
1let coreConfig =CoreConfig(clientID:"CLIENT_ID",environment:.sandbox)
2let cardClient =CardClient(config: coreConfig)
3. Get Order ID
On your server:
- Create an
ORDER_ID
by using the Orders v2 API.
- Pass your
ACCESS_TOKEN
in the Authorization
header. To get an ACCESS_TOKEN
, use the Authentication API.
Note: This access token is only for the sandbox environment. When you're ready to go live, request a live access token by changing the request sandbox endpoint to https://api-m.paypal.com/v1/oauth2/token.
- Pass the
intent
. You'll need to pass either AUTHORIZE
or CAPTURE
as the intent
type. This type must match the /authorize
or /capture
endpoint you use to process your order.
Sample request
1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/' \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Bearer ACCESS_TOKEN' \
4 --data-raw '{
5 "intent": "CAPTURE|AUTHORIZE",
6 "purchase_units": [
7 {
8 "amount": {
9 "currency_code": "USD",
10 "value": "5.00"
11 }
12 }
13 ]
14 }'
Sample response
1{
2"id":"ORDER_ID",
3"status":"CREATED"
4}
When a buyer starts a payment, send the ORDER_ID
from your server to your client app.
4. Create card request
A CardRequest
object:
- Attaches a card to an
ORDER_ID
.
- Launches 3D Secure when a payment requires additional authentication.
1. Collect card payment details
Build a card
object with the buyer's card details:
1let card =Card(
2number:"4005519200000004",
3expirationMonth:"01",
4expirationYear:"2025",
5securityCode:"123",
6cardholderName:"Jane Smith",
7billingAddress:Address(
8addressLine1:"123 Main St.",
9addressLine2:"Apt. 1A",
10locality:"City",
11region:"IL",
12postalCode:"12345",
13countryCode:"US"
14)
15)
Collecting a billing address can reduce the number of authentication challenges to customers.
2. Build CardRequest
Build a CardRequest
with the card
object and your ORDER_ID
:
1let cardRequest =CardRequest(
2orderID:"ORDER_ID",
3card: card,
4sca:.scaAlways
5)
3D Secure is supported for all card payments to comply with the Second Payment Services Directive (PSD2). PSD2 is a European Union regulation that introduces Strong Customer Authentication (SCA) and other security requirements.
Select your SCA launch option type using the sca
parameter in the CardRequest
initializer:
SCA.scaWhenRequired
launches an SCA challenge when applicable. This is enabled by default.
SCA.scaAlways
requires an SCA challenge for all card transactions.
5. Approve order
After your CardRequest
has the card details, call cardClient.approveOrder()
to process the payment.
1classMyViewController:UIViewController{
2 func cardCheckoutTapped(cardRequest:CardRequest){
3 cardClient.approveOrder(request: cardRequest)
4}
5}
6. Handle payment result scenarios
Set up your CardDelegate
to handle successful payments, errors, cancellations, and 3D Secure transaction flows.
1extension MyViewController:CardDelegate{
2 func setupCardClient(){
3 cardClient.delegate= self
4}
5
6 func card(_ cardClient:CardClient, didFinishWithResult result:CardResult){
7
8}
9 func card(_ cardClient:CardClient, didFinishWithError error:CoreSDKError){
10
11}
12 func cardDidCancel(_ cardClient:CardClient){
13
14}
15 func cardThreeDSecureWillLaunch(_ cardClient:CardClient){
16
17}
18 func cardThreeDSecureDidFinish(_ cardClient:CardClient){
19
20}
21}
7. Authorize and capture order
Submit your ORDER_ID
for authorization or capture when the PayPal iOS SDK calls the didFinishWithResult
method.
Call the authorize
endpoint of the Orders V2 API to place the money on hold:
Sample request: Authorize order
1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER_ID/authorize' \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Bearer ACCESS_TOKEN' \
4 --data-raw ''
Call the capture
endpoint of the Orders V2 API to capture the money immediately:
Sample request: Capture order
1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER_ID/capture' \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Bearer ACCESS_TOKEN' \
4 --data-raw ''
8. Test integration
Before going live, test your integration in the sandbox environment.
Learn more about the following resources on the Card Testing page:
Note: Use the credit card generator to generate additional test credit cards for sandbox testing.
When prompted for required data for the sandbox business request, such as a phone number, enter any number that fits the required format. Because this is a sandbox request, the data doesn't have to be factual.
Before you go live, you'll need to complete live onboarding to be eligible to process cards with your live PayPal account.