Convert billing agreements to payment tokens

Partners

The Payment Method Token API saves payment methods so payers don't have to enter details for future transactions. After payers save a payment method, payers can check out faster. You can also charge payers for subscriptions using payment methods such as PayPal, Venmo, cards, and Apple Pay.

You can use billing agreements you created with the Billing API to charge your customers. Convert billing agreements to payment tokens to use billing agreements with the Payment Method Tokens API.

When you convert billing agreements to payment tokens, you can use a single integration with the Payment Method Tokens API to manage PayPal, cards, Venmo, and Apple Pay, depending on market availability.

Know before you code

This server-side integration uses the Payment Method Tokens REST API.

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

Your account must already be configured for billing agreements to set up a reference transaction. Contact your account manager for details.

How it works

After your account is enabled to save payment methods, you can pass billing agreement IDs one-by-one to the /v3/vault/payment-tokens endpoint.

The endpoint returns a payment method token and a PayPal-generated customer ID.

Note: For a payer with multiple billing agreements, pass the PayPal-generated customer ID returned from the first API response in all subsequent API request payloads. This links the payer's PayPal-generated customer ID to their multiple payment tokens.

Follow the v3 vault guide to build the return payer experience using the generated payment method token and customer ID.

Request

Use existing billing agreement IDs to generate a payment token using payment method endpoint for a given payer. Copy the sample request code to generate a payment token:

Platform

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            "type": "BILLING_AGREEMENT",
9            "id": "B-7LT926395E2643345"
10          }
11      }
12  }'

Modify the code

Copy the code sample.
Change ACCESS-TOKEN to your sandbox access token.
Change REQUEST-ID to a unique alphanumeric set of characters such as a time stamp.
Use your billing agreement ID to pass in the payment source parameter and type as the BILLING_AGREEMENT

1{
2   "id": "jwgvx42",
3   "customer": {
4     "id": "customer_4029352050"
5   },
6   "payment_source": {
7     "paypal": {
8       "description": "Description for PayPal to be shown to PayPal payer",
9       "usage_pattern": "IMMEDIATE",
10        "shipping": {
11          "name": {
12            "full_name": "Firstname Lastname"
13          },
14          "address": {
15            "address_line_1": "123 Main St",
16            "address_line_2": "Unit B",
17            "admin_area_2": "Anytown",
18            "admin_area_1": "CA",
19            "postal_code": "12345",
20            "country_code": "US"
21          }
22        },
23        "permit_multiple_payment_tokens": false,
24        "usage_type": "PLATFORM",
25        "customer_type": "CONSUMER",
26        "email_address": "sb-fxn7p19501465@personal.example.com",
27        "payer_id": "AJM9JTWQJCFTA"
28      }
29    },
30    "links": [
31      {
32        "rel": "self",
33        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
34        "method": "GET",
35        "encType": "application/json"
36      },
37      {
38        "rel": "delete",
39        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
40        "method": "DELETE",
41        "encType": "application/json"
42      }
43    ]
44  }

Merchant

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 -H "PayPal-Auth-Assertion: AUTH-ASSERTION-TOKEN" \
6 -d '{
7             "payment_source": {
8                 "token": {
9                  "type": "BILLING_AGREEMENT",
10                  "id": "B-7LT926395E2643345"
11                  }
12              }
13          }'

Modify the code

Copy the code sample.

Change ACCESS-TOKEN to your sandbox access token.

Change REQUEST-ID to a unique alphanumeric set of characters such as a time stamp.

Change AUTH-ASSERTION-TOKEN to your PayPal-Auth-Assertion token.

Use your billing agreement ID to pass in the payment source parameter and type as the BILLING_AGREEMENT.

Sample API response

1{
2   "id": "jwgvx42",
3   "customer": {
4     "id": "customer_4029352050"
5   },
6   "payment_source": {
7     "paypal": {
8       "description": "Description for PayPal to be shown to PayPal payer",
9       "usage_pattern": "IMMEDIATE",
10        "shipping": {
11          "name": {
12            "full_name": "Firstname Lastname"
13          },
14          "address": {
15            "address_line_1": "123 Main St.",
16            "address_line_2": "Unit B",
17            "admin_area_2": "Anytown",
18            "admin_area_1": "CA",
19            "postal_code": "12345",
20            "country_code": "US"
21          }
22        },
23        "permit_multiple_payment_tokens": false,
24        "usage_type": "MERCHANT",
25        "customer_type": "CONSUMER",
26        "email_address": "consumer@example.com",
27        "payer_id": "AJM9JTWQJCFTA"
28      }
29    },
30    "links": [
31      {
32        "rel": "self",
33        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
34        "method": "GET",
35        "encType": "application/json"
36      },
37      {
38        "rel": "delete",
39        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
40        "method": "DELETE",
41        "encType": "application/json"
42      }
43    ]
44  }

Step result

A successful request returns the following:

An HTTP response code of 200 or 201. Returns 200 for an idempotent request.

The ID of the token in the id field.

The following 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.

Error descriptions

Issue	Message	Description
`EXACTLY_ONE_FIELD_REQUIRED`	Exactly one payment source is required.	The request is not well-formed, is syntactically incorrect, or violates schema.
`INACTIVE_BILLING_AGREEMENT`	Billing Agreement is not active.	The billing agreement is not active state can't be saved or used for purchase.
`INTERNAL_SERVER_ERROR`	A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server.	An internal server error occurred.
`MALFORMED_REQUEST_JSON`	The request JSON is not well formed.	The request is not well-formed, is syntactically incorrect, or violates schema.
`MISSING_REQUIRED_PARAMETER`	A required field or parameter is missing.	The request is not well-formed, is syntactically incorrect, or violates schema.
`NOT_ENABLED_TO_VAULT_PAYMENT_SOURCE`	The API caller or the merchant on whose behalf the API call is initiated is not allowed to vault the given source. Please contact PayPal customer support for assistance.	Authorization failed due to insufficient permissions.
`PAYPAL_REQUEST_ID_PREVIOUSLY_USED`	The PayPal-Request-ID has already been used for another request.	The requested action could not be performed, is semantically incorrect, or failed business validation.
`PERMISSION_DENIED`	You do not have permission to access or perform operations on this resource.	Authorization failed due to insufficient permissions.
`TOKEN_NOT_FOUND`	The specified token ID does not exist.	The requested resource ID was not found.
`TOKEN_PROVIDED_NOT_SUPPORTED`	422 unprocessable entity	The token provided is not currently supported.

Webhook

Event	Trigger	Payment methods
`VAULT.PAYMENT-TOKEN.CREATED`	A payment method token is created to save a payment method.	PayPal