Convert billing agreements to payment tokens

DOCSCurrent

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

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

    1. Copy the code sample.
    2. Change ACCESS-TOKEN to your sandbox access token.
    3. Change REQUEST-ID to a unique alphanumeric set of characters such as a time stamp.
    4. 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 or 201. Returns 200 for an idempotent request.
      • The ID of the token in the id field.
      • The following HATEOAS links:
      RelMethodDescription
      selfGETMake a GET request to this link to retrieve data about the saved payment method.
      deleteDELETEMake a DELETE request to delete the payment token.

      Error descriptions

      IssueMessageDescription
      EXACTLY_ONE_FIELD_REQUIREDExactly one payment source is required.The request is not well-formed, is syntactically incorrect, or violates schema.
      INACTIVE_BILLING_AGREEMENTBilling Agreement is not active.The billing agreement is not active state can't be saved or used for purchase.
      INTERNAL_SERVER_ERRORA 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_JSONThe request JSON is not well formed.The request is not well-formed, is syntactically incorrect, or violates schema.
      MISSING_REQUIRED_PARAMETERA required field or parameter is missing.The request is not well-formed, is syntactically incorrect, or violates schema.
      NOT_ENABLED_TO_VAULT_PAYMENT_SOURCEThe 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_USEDThe 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_DENIEDYou do not have permission to access or perform operations on this resource.Authorization failed due to insufficient permissions.
      TOKEN_NOT_FOUNDThe specified token ID does not exist.The requested resource ID was not found.
      TOKEN_PROVIDED_NOT_SUPPORTED422 unprocessable entityThe token provided is not currently supported.

      Webhook

      EventTriggerPayment methods
      VAULT.PAYMENT-TOKEN.CREATEDA payment method token is created to save a payment method.PayPal

      We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies