Save cards for purchase later with the iOS SDK

Save customer credit or debit cards to charge them at a later time. For example, you can offer a free trial and charge payers after the trial expires. Payers don't need to be present when charged and no checkout is required.

Use the iOS SDK to save a payer's credit or debit cards.

Availability

Know before you code

• To save payment methods, you must be able to identify payers uniquely. For example, payers create an account and log in to your app.

• Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:

  • Your sandbox account login information
  • Your access token

• The iOS SDK saves the following card types for purchase later:

  • American Express
  • Discover
  • Mastercard
  • Visa

• You'll need an existing advanced credit and debit integration. PayPal must approve your business account for advanced credit and debit card payments.

How it works

PayPal encrypts payment method information and stores it in a digital vault for that customer.

1. The payer saves their payment method.
2. For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
3. Use the customer ID to retrieve saved payment methods and add new ones for existing customers in your application.

The checkout process is now shorter because it uses saved payment information.

1. Set up account to save payments

Set up your sandbox and live business accounts to save payment methods:

1. Log in to the Developer Dashboard.
2. Under REST API apps, select your app name.
3. Under Sandbox App Settings > App Feature Options, check Accept payments.
4. Expand Advanced options. Confirm that Vault is selected.

2. Add the CardPayments module to your app

Add the CardPayments package dependency for your app using Swift Package Manager or CocoaPods:

3. Add a button to initiate vault

Add a button to your app's UI to save a card.

1Button("Save Card") {
2   // Create a setup token on server-side (see next step)
3}

4. Create setup token

On your server, you need to create a setup token.

From your server, create a setup token for cards that have:

• No verification
• 3D Secure verification

1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer ACCESS-TOKEN" \
4 -H "PayPal-Request-Id: REQUEST-ID" \
5 -d '{
6      "payment_source": {
7        "card": {}
8      }
9  }'

1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer ACCESS-TOKEN" \
4 -H "PayPal-Request-Id: REQUEST-ID" \
5 -d '{
6      "payment_source": {
7        "card": {}
8      }
9      "customer": {
10         "id": "llPdZofmwR"
11      }
12    }'

1{
2  "id": "86S246162E316080B", 
3  "customer": {
4    "id": "ZUzLMNMrJD" 
5    },
6  "status": "CREATED",
7  "payment_source": {
8      "card": {}
9    },
10  "links": [{
11    "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/86S246162E316080B",
12    "rel": "self",
13    "method": "GET",
14    "encType": "application/json"
15    }]
16   }

5. Implement vaulting in iOS SDK

In the iOS SDK, you need to create a CardVaultRequest to pass into the vault function.

The vault method:

• Attaches a card to a setup token.
• 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(
2  number: "4005519200000004",
3  expirationMonth: "01",
4  expirationYear: "2025",
5  securityCode: "123",
6  cardholderName: "Jane Smith",
7  billingAddress: Address(
8    addressLine1: "123 Main St.",
9    addressLine2: "Apt. 1A",
10    locality: "City",
11    region: "IL",
12    postalCode: "12345",
13    countryCode: "US"
14  )
15)

Collecting a billing address can reduce the probability of an authentication challenge.

2. Build CardVaultRequest

Build a CardVaultRequest with the card object and your SETUP-TOKEN:

1let cardVaultRequest = CardVaultRequest(
2  setupTokenID: "SETUPTOKEN",
3  card: card
4)

3. Call the vault function

After your CardVaultRequest has the card details and setupTokenID, call cardClient.vault() to process the payment.

1let config = CoreConfig(clientID: "CLIENT_ID", environemnt: .live)
2let cardClient = CardClient(config: config)
3cardClient.vaultDelegate = self
4cardClient.vault(cardVaultRequest)

4. Handle vault result scenarios

1extension MyViewController: CardVaultDelegate {
2  // MARK: - CardVaultDelegate
3  func card(_ cardClient: CardClient, didFinishWithVaultResult vaultResult: CardVaultResult) {
4    // Vaulting has been approved and is ready to be used to create a paymentToken or vaultID
5    // The CardVaultResult contains a setupTokenID string used to create the paymentToken from your server
6    // Make sure you pass the cardVaultResult.setupTokenID to your server
7  }
8  func card(_ cardClient: CardClient, didFinishWithVaultError error: CoreSDKError) {
9    // Handle the error by accessing `error.localizedDescription`
10  }
11  func cardVaultDidCancel(_ cardClient: CardClient) {
12    // 3D Secure auth was canceled by the user
13  }
14  func cardThreeDSecureWillLaunch(_ cardClient: CardClient) {
15    // 3D Secure auth will launch
16  }
17  func cardThreeDSecureDidFinish(_ cardClient: CardClient) {
18    // 3D Secure auth finished
19  }
20}

6. Create a payment token with the vault setup token ID

Convert the setup token to a payment token that can be used to process a transaction:

1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens' \
2 -H "Content-Type: application/json" \
3 -H "Authorization: Bearer ACCESS-TOKEN" \
4 -H "PayPal-Request-Id: REQUEST-ID" \
5 -d '{
6      "payment_source": {
7          "token": {
8              "id": "VAULT-SETUP-TOKEN",
9              "type": "SETUP_TOKEN"
10          }
11      }
12  }'

Modify the code

1. Change ACCESS-TOKEN to your sandbox app's access token.
2. Change REQUEST-ID to a set of unique alphanumeric characters such as a timestamp.
3. Change VAULT-SETUP-TOKEN to the value passed from the client.
4. Save the resulting payment token returned from the API to use in future transactions.

7. Show saved payment methods to returning payers

When a payer returns to your app, you can show the payer's saved payment methods with the Payment Method Tokens API.

List all saved payment methods

Make the server-side list all payment tokens API call to retrieve payment methods saved to a payer's PayPal-generated customer ID. Based on this list, you can show all saved payment methods to a payer to select during checkout.

Important: Don't expose payment method token IDs on the client side. To protect your payers, create separate IDs for each token and use your server to correlate them.

Sample request: List all saved payment methods

1curl -L -X GET "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=CUSTOMER-ID"\
2 -H "Content-Type: application/json" \
3 -H "Accept-Language: en_US" \
4 -H "Authorization: Bearer ACCESS-TOKEN" \
5 -H "PayPal-Request-Id: REQUEST-ID"

Modify the code

• Change CUSTOMER-ID to a PayPal-generated customer ID.
• Change ACCESS-TOKEN to your sandbox app's access token.
• Change REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.

Show saved card to payer

Display the saved card to the payer and use the Orders API to make another transaction. Use the vault ID the payer selects as an input to the Orders API to capture the payment.

We recommend showing the card brand and the last 4 digits.

8. Test your integration

Run the following tests in the PayPal sandbox to ensure that you can save cards.

Save payment

1. In your app, initiate the vault.
2. Create a setup token with an empty card.
3. Call the vault function in the SDK with setup token and card details.
4. Create a payment token with the updated setup token.
5. Store the PayPal-generated customer ID in your system.
6. Log in to sandbox with your merchant account and verify the transaction.
7. Return to your app and initiate another transaction. Use the PayPal-generated payment token as a payment source.
8. Verify that the transaction captures successfully without having to complete PayPal Web Checkout again.

Next steps

• Test and go live with this integration.
• Change the credentials and API URLs from api-m.sandbox.paypal.com to api-m.paypal.com when going live with your integration.
• You can create orders without the payment_source.paypal.attributes.vault for subsequent or recurring transactions.
• You can get a payment token, list all payment tokens, delete a payment token, and more with the Payment Method Tokens API.