Save cards with the Payment Method Tokens API

CurrentLast updated: November 7th 2023, @ 9:47:43 am

Select a payment method

No transaction is required when payment methods are saved with the Payment Method Tokens API. You can charge payers after a set amount of time. Payers don't need to be present when charged. A common use case is offering a free trial and charging payers after the trial expires.

Availability

Australia
Austria
Belgium
Bulgaria
Canada
China
Cyprus
Czech Republic
Denmark
Estonia
Finland
France
Germany
Hungary
Ireland
Italy
Latvia
Liechtenstein
Lithuania
Luxembourg
Malta
Netherlands
Norway
Poland
Portugal
Romania
Slovakia
Slovenia
Spain
Sweden
United Kingdom
United States

Know before you code

This server-side integration uses the Payment Method Tokens REST API.
The Payment Method Tokens API supports saving cards and PayPal Wallets.
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

You'll need an existing advanced credit and debit card payments integration. PayPal must approve your business account for advanced credit and debit card payments.
The Payment Method Tokens API requires SAQ D PCI Compliance.

1. Create setup token for card

Create a setup token for cards that have:

No verification
Smart authorization
3D Secure verification

When saving a card for the first time for a payer, the response to the setup token request returns the customer.id and the setup_token_id.

Tip: For a payer with previously stored payment_sources, pass the PayPal-generated customer.id in the setup token request. Then you can link additional payment_sources to this payer.

Platform
Merchant

Setup token for card with no verification

There's usually no transaction when saving a card and creating a setup token. The data passed to the API is only checked for format.

Sample API request

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              "number": "4111111111111111",
9              "expiry": "2027-02",
10              "name": "Firstname Lastname",
11              "billing_address": {
12                  "address_line_1": "2211 N First Street",
13                  "address_line_2": "17.3.160",
14                  "admin_area_1": "CA",
15                  "admin_area_2": "San Jose",
16                  "postal_code": "95131",
17                  "country_code": "US"
18              },
19              "experience_context": {
20                  "brand_name": "YourBrandName",
21                  "locale": "en-US",
22                  "return_url": "https://example.com/returnUrl",
23                  "cancel_url": "https://example.com/cancelUrl"
24              }
25          }
26      }
27  }'

Modify the code

Copy the sample request code.
Change ACCESS-TOKEN to your sandbox access token.
Change REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.

Step result

A successful request returns the following:

HTTP response code HTTP 2xx or HTTP 200.
The ID of the token in the id field.
HATEOAS links:

Rel	Method	Description
`self`	`GET`	Make a GET request to this link to retrieve payment source data associated with the setup token ID.
`confirm`	`POST`	Make a POST request to generate the payment token using the approved setup token.

Sample API response

1{
2  "id": "5C991763VB2771612",
3  "customer": {
4    "id": "customer_4029352050"  
5  },
6  "status": "APPROVED",
7  "payment_source": {
8    "card": {
9      "name": "Firstname Lastname"
10      "last_digits": "1111",
11      "expiry": "2027-02",
12      "billing_address": {
13        "address_line_1": "2211 N First Street",
14        "address_line_2": "17.3.160",
15        "admin_area_2": "San Jose",
16        "admin_area_1": "CA",
17        "postal_code": "95131",
18        "country_code": "US"
19      }
20    }
21  },
22  "links": [
23    {
24      "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
25      "rel": "self",
26      "method": "GET",
27      "encType": "application/json"
28    },
29    {
30      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens",
31      "rel": "confirm",
32      "method": "POST",
33      "encType": "application/json"
34    }
35  ]
36}

2. Create payment token

Use an approved setup token to save the payer's credit or debit card. Then, copy the sample request code to generate a payment token:

Platform
Merchant

Sample API request

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": "5C991763VB2781612",
9              "type": "SETUP_TOKEN"
10          }
11      }
12  }'

Modify the code

Copy the sample request code.
Change ACCESS-TOKEN to your sandbox access token.
Change REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.
Use token as the payment source and complete the rest of the source object for your use case and business.
Use your setup token ID to pass in the payment source parameter and type of the SETUP_TOKEN.

Step result

A successful request results in the following:

HTTP response code HTTP 2xx or HTTP 200.
ID of the payment token and the associated payment method information.
HATEOAS links:

Rel	Method	Description
`self`	`GET`	Make a GET request to this link to retrieve data about the saved method.
`delete`	`DELETE`	Make a DELETE request to delete the saved payment token.

Sample API response

1{
2  "id": "dnbbj3g",
3  "customer": {
4    "id": "customer_4029352050"
5  },
6  "payment_source": {
7    "card": {
8      "name": "Firstname Lastname",
9      "last_digits": "1111",
10      "brand": "VISA",
11      "expiry": "2027-02",
12      "billing_address": {
13        "address_line_1": "2211 N First Street",
14        "address_line_2": "17.3.160",
15        "admin_area_2": "San Jose",
16        "admin_area_1": "CA",
17        "postal_code": "95131",
18        "country_code": "US"
19      }
20    }
21  },
22  "links": [
23    {
24      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/dnbbj3g",
25      "rel": "self",
26      "method": "GET",
27      "encType": "application/json"
28    },
29    {
30      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/dnbbj3g",
31      "rel": "delete",
32      "method": "DELETE",
33      "encType": "application/json"
34    }
35  ]
36}

3. Use saved payment token

After you create a payment method token, use the token instead of the payment method to create a purchase and capture the payment with the Orders API.

You can store a Merchant Customer ID aligned with your system to simplify the mapping of customer information within your system and PayPal. This is an optional field that will return the value shared in the response.

Set the payment_source to specify the payment source type. Set the vault_id to the payment method token you received.

Sample API request with payment token associated with card

Platform
Merchant

Modify the following code sample:

1curl -v -X POST ' https://api-m.sandbox.paypal.com/v2/checkout/orders' \
2 -H "PayPal-Request-Id: REQUEST-ID" \
3 -H "Authorization: Bearer ACCESS-TOKEN" \
4 -H "PayPal-Partner-Attribution-ID: BN-CODE" \
5 -H "Content-Type: application/json" \
6 -d '{
7      "intent": "CAPTURE",
8      "purchase_units": [
9          {
10              "amount": {
11                  "currency_code": "USD",
12                  "value": "100.00"
13              },  
14              "payee": {  
15                  "merchant_id": "MERCHANT-ID"  
16              }
17          }
18      ],
19      "payment_source": {
20          "card": {
21              "vault_id":"dnbbj3g"
22          }          
23      }
24  }'

Modify the code

Copy the sample request code.
Change ACCESS-TOKEN to your sandbox access token.
Change REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.
For vault.id, enter the ID of your payment method token.

Sample API response

1{
2  "id": "5O190127TN364715T",
3  "status": "COMPLETED",
4  "payment_source": {
5    "card": {
6      "attributes": {
7          "customer": {
8              "id": "customer_4029352050"
9          }
10      }       
11      "brand": "VISA",
12      "last_digits": "1111"
13    }
14  }
15  "purchase_units": [
16    {
17      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
18      "payments": {
19        "captures": [
20          {
21            "id": "3C679366HH908993F",
22            "status": "COMPLETED",
23            "amount": {
24              "currency_code": "USD",
25              "value": "100.00"
26            },
27            "payee": {
28                "email_address": "testing_1667534678@paypal.com"
29            },
30            "seller_protection": {
31              "status": "NOT_ELIGIBLE"
32            },
33            "final_capture": true,
34            "seller_receivable_breakdown": {
35              "gross_amount": {
36                "currency_code": "USD",
37                "value": "100.00"
38              },
39              "paypal_fee": {
40                "currency_code": "USD",
41                "value": "3.00"
42              },
43              "net_amount": {
44                "currency_code": "USD",
45                "value": "97.00"
46              }
47            },
48            "create_time": "2022-01-01T21:20:49Z",
49            "update_time": "2022-01-01T21:20:49Z",
50            "links": [
51              {
52                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/3C679366HH908993F",
53                "rel": "self",
54                "method": "GET"
55              },
56              {
57                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
58                "rel": "refund",
59                "method": "POST"
60              },
61              {  
62                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",  
63                "rel": "up",  
64                "method": "GET"  
65              }
66            ]
67          }
68        ]
69      }
70    }
71  ],
72  "links": [
73    {
74      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
75      "rel": "self",
76      "method": "GET"
77    }
78  ]
79}

Use payment token on behalf of payer

When the payer isn't present to check out, you can use the payment method token to create an order on behalf of the payer.

1. Retrieve a payer's payment method token

If you stored the payment token the payer created on your site, skip this step.

To make a payment on behalf of the payer, retrieve the payment token they created. You'll need the customer ID that you assigned to this payer when saving the payment method.

Sample API request

API endpoint used: Payment tokens

Platform
Merchant

1curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050' \
2 -H "Authorization: Bearer ACCESS-TOKEN" \
3 -H "Content-Type: application/json"

Modify the code

Copy the code sample.
Change ACCESS-TOKEN to your sandbox access token.
Pass the PayPal-generated customer_id to retrieve the payment token details associated with the payer.
The response will return the Merchant Customer ID if it was passed during payment token creation.

Sample API response

1{
2  "customer": {
3    "id": "customer_4029352050"
4  },
5  "payment_tokens": [
6    {
7      "id": "dnbbj3g",
8      "customer": {
9        "id": "customer_4029352050"    
10      },
11      "payment_source": {
12        "card": {
13          "last_digits": "1111",
14            "expiry": "2027-02",
15            "brand": "VISA",
16            "billing_address": {
17              "address_line_1": "2211 N First Street",
18              "address_line_2": "17.3.160",
19              "admin_area_2": "San Jose",
20              "admin_area_1": "CA",
21              "postal_code": "95131",
22              "country_code": "US"
23            }
24          }
25        }
26      },
27      "links": [
28        {
29          "rel": "self",
30          "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/dnbbj3g",
31          "method": "GET",
32          "encType": "application/json"
33        },
34        {
35          "rel": "delete",
36          "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/dnbbj3g",
37          "method": "DELETE",
38          "encType": "application/json"
39        }
40      ]
41    }
42  ],
43  "links": [
44    {
45      "rel": "self",
46      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false",
47      "method": "GET",
48      "encType": "application/json"
49    },
50    {
51      "rel": "first",
52      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false",
53      "method": "GET",
54      "encType": "application/json"
55    },
56    {
57      "rel": "last",
58      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352050&page=1&page_size=5&total_required=false",
59      "method": "GET",
60      "encType": "application/json"
61    }
62  ]
63}

Step result

A successful request returns the following:

HTTP response code HTTP 2xx or HTTP 200.
Payment method details and status for the payment token.
JSON response body that includes all payment method tokens.
HATEOAS links:

Rel	Method	Description
`self`	`GET`	Make a GET request to this link to retrieve data about the saved payment method.
`delete`	`DELETE`	Make a DELETE request to delete the saved payment token.

2. Use payment method token with checkout

After you get the payment method token ID, you can use a payment method token with checkout to create your order.

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.

Save cards with the Payment Method Tokens API

Availability

Know before you code

1. Create setup token for card

Setup token for card with no verification

Sample API request

Modify the code

Step result

Sample API response

2. Create payment token

Sample API request

Modify the code

Step result

Sample API response

3. Use saved payment token

Sample API request with payment token associated with card

Modify the code

Sample API response

Use payment token on behalf of payer

1. Retrieve a payer's payment method token

Sample API request

Modify the code

Sample API response

Step result

2. Use payment method token with checkout

Webhooks for saving payment methods

See also