Convert billing agreements to payment tokens
Last updated: Aug 15th, 5:53am
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.
- 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 }'
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
.
Sample API response
1{2 "id": "0rjhvf82",3 "customer": {4 "id": "customer_12345"5 },6 "payment_source": {7 "paypal": {8 "description": "Description for PayPal to be shown to PayPal payer",9 "usage_type": "MERCHANT",10 "customer_type": "CONSUMER",11 "email_address": "consumer@example.com",12 "payer_id": "B2Y3KG6U5J3NC",13 "name": {14 "given_name": "Firstname",15 "surname": "Lastname",16 "full_name": "Firstname Lastname"17 },18 "tenant": "PAYPAL"19 }20 },21 "links": [22 {23 "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/0rjhvf82",24 "rel": "self",25 "method": "GET",26 "encType": "application/json"27 },28 {29 "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/0rjhvf82",30 "rel": "delete",31 "method": "DELETE",32 "encType": "application/json"33 }34 ]35 }
Step result
A successful request returns the following:
- An HTTP response code of
200
or201
. Returns200
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 |