Save cards with the Orders API
Last updated: Nov 4th, 9:33am
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"
- thevault.id
is returned"APPROVED"
- subscribe to theVAULT.PAYMENT-TOKEN.CREATED
[webhook](/api/rest/webhooks/) to receive avault.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.
See also
- Errors
- To keep saved cards up to date, see the Real-time account updater.