Convert billing agreements to payment tokens

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

1. 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.
2. 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.

3. 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:

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  }'

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  }

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:

Error descriptions

Webhook