Save cards with the Orders API

DocsCURRENT

Last updated: May 5th, 11:07pm

After customers save their credit or debit card, they can select it for faster checkout. Customers won't have to enter payment details for future transactions.

Save cards with the Orders API if you want to save cards during checkout but aren't PCI Compliant - SAQ A.

Know before you code

The Orders API supports saving PayPal and card payment methods only.

Passing card data to the Orders API requires you to be PCI Compliant - SAQ D.

Contact your account manager to configure your account to save payment methods.

You'll need to have an existing advanced credit and debit card payments integration. PayPal must approve your account to process advanced credit and debit card payments.

How it works

When a payer on your website saves their payment method, PayPal creates a customer record. PayPal then encrypts the payment method information and stores it in a digital vault. The vault is accessible only by the billing agreement holder.

The payer saves their payment method.
For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
Pass a call into the Orders API. Include the payment method, customer ID, and an indication that the payment method should be saved.
If the order is processed and the payment method is saved, you receive a payment method token in the Orders API response.
Pass the payment method token into the Orders API to populate the checkout page with the saved payment method.

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

Save card fields

Make a server-side API call to create the order and save the card at the same time. When a payer is using a card to check out, the Orders API can capture the payment in a single request.

Use 3D Secure authentication to reduce the likelihood of fraud and improve transaction performance with supported cards. In some countries, authorizing a card can trigger a 3D Secure contingency. 3D Secure verification may occur in PSD2 countries, including members of the EU. For 3D Secure verification, pass SCA_ALWAYS or SCA_WHEN_REQUIRED in the payment_source.card.attributes.verification.method field for the create order request. The API response returns the order status as PAYER_ACTION_REQUIRED.

Save card fields for a returning payer

Create your own UI to show saved payment methods for returning payers.

Call the List All Payment Tokens API server-side to retrieve all payment methods saved for a payer. Identify the payer using the PayPal-generated customer.id. From this list, you can show all saved payment methods to a payer to allow them to select one during checkout.

In the following sample, the authorize and capture requests occur in a single request, and the card is stored in the vault with 3D Secure verification when required.

Save card fields at the platform level

Sample requests and responses for the create order and save card, and the list all payment tokens APIs:

Sample request - First-time payer
Sample request - Returning payer
Sample response - Returning payer

1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
2 -H 'Accept: application/json' \
3 -H 'Content-Type: application/json' \
4 -H 'Accept-Language: en_US' \
5 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
6 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
7 -H 'Authorization: Bearer ACCESS-TOKEN' \
8 -H 'PayPal-Request-ID: 1337623214'\
9 -d '
10  {
11    "intent": "CAPTURE",
12    "payment_source": {
13        "card": {
14            "number": "4009348888881881",
15            "expiry": "2026-02",
16            "name": "Firstname Lastname",
17            "billing_address": {
18                "address_line_1": "2211 N First Street",
19                "address_line_2": "Building 17",
20                "admin_area_2": "San Jose",
21                "admin_area_1": "CA",
22                "postal_code": "95131",
23                "country_code": "US"
24            },
25            "attributes": {
26                "verification": {
27                  "method": "SCA_WHEN_REQUIRED"
28                },
29                "vault": {
30                    "store_in_vault": "ON_SUCCESS",
31                }
32            }
33        }
34    },
35    "purchase_units": [
36        {
37            "amount": {
38                "currency_code": "USD",
39                "value": "101.00"
40            },
41            "payee": {
42              "merchant_id": "MERCHANT-ID"  
43            }
44        }
45    ]
46}'

Save card fields at the merchant level

Sample requests and responses for the create order and save card, and the list all payment tokens APIs:

Sample request - First-time payer
Sample response - First-time payer
Sample request - Returning payer
Sample response - Returning payer

1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
2 -H 'Accept: application/json' \
3 -H 'Content-Type: application/json' \
4 -H 'Accept-Language: en_US' \
5 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
6 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
7 -H 'Authorization: Bearer ACCESS-TOKEN' \
8 -H 'PayPal-Request-ID: 1337623214' \
9 -d '
10  {
11    "intent": "CAPTURE",
12    "payment_source": {
13        "card": {
14            "number": "4009348888881881",
15            "expiry": "2024-02",
16            "name": "Firstname Lastname",
17            "billing_address": {
18                "address_line_1": "2211 N First Street",
19                "address_line_2": "Building 17",
20                "admin_area_2": "San Jose",
21                "admin_area_1": "CA",
22                "postal_code": "95131",
23                "country_code": "US"
24            },
25            "attributes": {
26                "verification": {
27                  "method": "SCA_WHEN_REQUIRED"
28                },
29                "vault": {
30                    "store_in_vault": "ON_SUCCESS",
31                }
32            }
33        }
34    },
35    "purchase_units": [
36        {
37            "amount": {
38                "currency_code": "USD",
39                "value": "101.00"
40            }
41        }
42    ]
43}'

Modify the code

The payment_source.card.attributes.vault stores the card information as the vault.id. Use the vault.id future payments. Check the Orders API attributes.vault.status object for the following responses:

"VAULTED" - the vault.id is returned

"APPROVED" - subscribe to the VAULT.PAYMENT-TOKEN.CREATED [webhook](/api/rest/webhooks/) to receive a vault.id

Save the customer.id and vault.id values in your database.

Because 3D Secure verification wasn't required in this example, the API response doesn't return PAYER_ACTION_REQUIRED as the order status.

Order capture response

An APPROVED status from the Orders capture response is shown in the following sample:

1"attributes": {
2  "vault": {
3    "status": "APPROVED",
4    "links": [
5      {
6        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
7        "rel": "up",
8        "method": "GET"
9      }
10    ]
11  }
12}

The card is saved. You can see the Vault Payment Token ID in the response of the Create payment token API call.

Webhooks for saving payment methods

Event	Trigger	Payment methods
`VAULT.PAYMENT-TOKEN.CREATED`	A payment token is created to save a payment method.	Cards and PayPal
`VAULT.PAYMENT-TOKEN.DELETED`	A payment token is deleted. The payer's payment method is no longer saved to the PayPal vault.	Cards and PayPal
`VAULT.PAYMENT-TOKEN.DELETION-INITIATED`	A request to delete a payment token has been submitted to the Payment Method Tokens API.	PayPal

For more information on webhooks, see webhooks.