Save PayPal with the Payment Method Tokens API

Current

Last updated: Oct 14th, 10:40am

Overview

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.

Customers with a PayPal Wallet can:

  • Review PayPal transactions and transaction history
  • Review, add, or remove funding sources
  • Review and cancel recurring payments
  • Hold a balance in their PayPal account
  • Use PayPal to send and receive money
  • Withdraw money to a linked bank account
  • Use PayPal to transact with merchants

Availability

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

Know before you code

  • This server-side integration uses the Payment Method Tokens 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 must be approved and have your account configured for billing agreements to set up a reference transaction. Contact your account manager for details.
1

Create setup token to save PayPal Wallet

The payer must authenticate and approve the creation of a billing agreement. Then you can create a setup token to save PayPal as a payment method.

The initial POST on setup-tokens completes the following actions:

  • Returns a PAYER_ACTION_REQUIRED status
  • Creates a temporary setup token
  • Redirects to the approve URL

When saving a payer's PayPal Wallet for first time, the response to the setup-token request returns the PayPal-generated customer.id and the setup_token_id.

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

To create a setup token for PayPal that triggers a payer action, copy and modify the following code:

  1. Platform sample API request
  2. Merchant sample API request
  3. Sample API response
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-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
5 -H "PayPal-Partner-Attribution-Id: BN-CODE" \
6 -H "PayPal-Request-Id: REQUEST-ID" \
7 -d '{
8      "customer": {
9        "merchant_customer_id": "customer@merchant.com"
10      },
11      "payment_source": {
12          "paypal": {
13              "description": "Description for PayPal to be shown to PayPal payer",
14              "shipping": {
15                  "name": {
16                      "full_name": "Firstname Lastname"
17                  },
18                  "address": {
19                      "address_line_1": "2211 N First Street",
20                      "address_line_2": "Building 17",
21                      "admin_area_2": "San Jose",
22                      "admin_area_1": "CA",
23                      "postal_code": "95131",
24                      "country_code": "US"
25                  }
26              },
27              "permit_multiple_payment_tokens": false,
28              "usage_pattern": "IMMEDIATE",
29              "usage_type": "PLATFORM",
30              "customer_type": "CONSUMER",
31              "experience_context": {
32                  "shipping_preference": "SET_PROVIDED_ADDRESS",
33                  "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
34                  "brand_name": "EXAMPLE INC",
35                  "locale": "en-US",
36                  "return_url": "https://example.com/returnUrl",
37                  "cancel_url": "https://example.com/cancelUrl"
38              }
39          }
40      }
41  }'

Modify the code

  1. Copy the code sample.
  2. Change ACCESS-TOKEN to your sandbox access token.
  3. Change PAYPAL-AUTH-ASSERTION to your PayPal-Auth-Assertion token.
  4. Change BN-CODE to your PayPal Attribution ID to receive revenue attribution. See Retrieve BN code.
  5. Change REQUEST-ID to a set of unique alphanumeric characters such as a timestamp.
  6. Use PayPal as the payment_source. Complete the rest of the source object for your use case and business.
  7. Update the return_url value with the URL where the payer is redirected after they approve the flow.
  8. Update the cancel_url value with the URL where the payer is redirected after they cancel the flow.

Step result

A successful request results in the following:

  • The HTTP response codes HTTP 2xx or HTTP 200.
  • A status of PAYER_ACTION_REQUIRED.
  • A setup token. In the previous sample response, the setup token is "id": "4G4976650J0948357". The setup token expires after 3 days. You'll exchange the setup token for a payment token in the next step.
  • HATEOAS links:
Rel Method Description
approve GET Use this link to take your payer through a PayPal-hosted approval flow.
confirm POST Make a POST request to use an approved setup token to save the PayPal Wallet and generate a payment token.
self GET Make a GET request to view the state of your setup token and payment method details.
2

Create payment token

You can store a Merchant Customer ID aligned with your system to simplify the mapping of customer information within your system and PayPal when creating a payment token. This is an optional field that will return the value shared in the response. Use an approved setup token to save the payer's payment method to the vault. Then, copy the sample request code to generate a payment token:

  1. Platform sample API request
  2. Merchant sample API request
  3. Sample API response
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-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
5 -H "PayPal-Partner-Attribution-Id: BN-CODE" \
6 -H "PayPal-Request-Id: REQUEST-ID" \
7 -d '{
8      "customer": {
9        "merchant_customer_id": "customer@merchant.com"
10      },
11      "payment_source": {
12          "token": {
13              "id": "4G4976650J0948357",
14              "type": "SETUP_TOKEN"
15          }
16      }
17  }'

Modify the code

  1. Copy the code sample.
  2. Change ACCESS-TOKEN to your sandbox access token.
  3. Change PAYPAL-AUTH-ASSERTION to your PayPal-Auth-Assertion token.
  4. Change BN-CODE to your PayPal Attribution ID to receive revenue attribution. See Retrieve BN code.
  5. Change REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.
  6. Use token as the payment source and complete the rest of the source object for your use case and business.
  7. Use your setup token ID to pass in the payment source parameter and type as the SETUP_TOKEN.

Step result

A successful request returns the following:

  • An HTTP response code HTTP 2xx or HTTP 200.
  • The ID of the payment token and associated payment method information.
  • 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 payment token from the vault.
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.

  1. Platform sample API request
  2. Merchant sample API request
  3. Sample API response
1curl -v -k -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-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
5 -H "PayPal-Partner-Attribution-Id: BN-CODE" \
6 -H "Content-Type: application/json" \
7 -d '{
8      "intent": "CAPTURE",
9      "purchase_units": [
10          {
11              "amount": {
12                  "currency_code": "USD",
13                  "value": "100.00"
14              },
15              "payee": {  
16                  "merchant_id": "MERCHANT-ID"  
17              }
18          }
19      ],
20      "payment_source": {
21          "paypal": {
22              "attributes": {
23                    "customer": {
24                        "merchant_customer_id": "customer@merchant.com"
25              },
26              "vault_id":"jwgvx42"
27          }          
28      }
29  }'

Modify the code

  1. Copy the code sample.
  2. Change ACCESS-TOKEN to your sandbox access token.
  3. Change PAYPAL-AUTH-ASSERTION to your PayPal-Auth-Assertion token.
  4. Change BN-CODE to your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
  5. Change REQUEST-ID to a set of unique alphanumeric characters such as a time stamp.
  6. Use the ID of your payment method token as the vault.id.

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.


API endpoint used: Payment tokens

  1. Platform sample API request
  2. Merchant sample API request
  3. Sample API response
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 "PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION" \
4 -H "PayPal-Partner-Attribution-Id: BN-CODE" \
5 -H "Content-Type: application/json"

Modify the code

  1. Copy the code sample.
  2. Change ACCESS-TOKEN to your sandbox access token.
  3. Pass the PayPal-generated customer.id to retrieve the payment token details associated with the payer.
  4. If stored in the payment token, the response will return the Merchant Customer ID.

Step result

A successful request results in the following:

  1. An HTTP response code of 200 OK.
  2. Payment method details and status for the provided payment token.
  3. 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 payment token from the vault.

2. Use saved payment method token

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.

See also

ReferencePayPal.comPrivacyCookiesSupportLegalContact

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more