Save cards with the JavaScript SDK

After customers save their credit or debit card, they can select it for faster checkout. Customers won't have to enter payment details for future transactions.

Use the JavaScript SDK to save a payer's card if you aren't PCI Compliant - SAQ A but want to save credit or debit cards during checkout.

Know before you code

This integration requires a PayPal Developer account.
You'll need to have an existing advanced credit and debit card payments integration. PayPal must approve your account to process advanced credit and debit card payments.
Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:
- The sandbox client ID and secret of your REST app.
- An access token to use the PayPal REST API server.
This client-side and server-side integration uses the following:
- PayPal JavaScript SDK
- Orders REST API

How it works

PayPal encrypts payment method information and stores it in a digital vault for that customer.

The payer saves their payment method.
For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
When the customer returns to your website and is ready to check out, pass their PayPal-generated customer ID to the JavaScript SDK. The customer ID tells the JavaScript SDK to save or reuse a saved payment method.
The payer completes a billing agreement.
The JavaScript SDK populates the checkout page with each saved payment method. Each payment method appears as a one-click button next to other ways to pay.

The checkout process is now shorter because it uses saved payment information.

Use cases

Businesses save payment methods if they want customers to:

Check out without re-entering a payment method
Pay after use, for example, ride-sharing and food delivery

Select platform or merchant

If you're a third-party saving payment method on behalf of merchants, select Merchant (see steps 1-7).

If you're a platform for hosting merchants, select Platform(see steps 3-7).

1. Generate user ID token for payer

Merchant (first-time payer)

A payer wants to save a payment method for the first time.

The PayPal OAuth 2.0 API has a response_type parameter. Set the response_type to id_token to retrieve a unique ID token for a payer when a payer saves a new payment method.

Sample server-side user ID token request

curl -s -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -u 'CLIENT-ID:CLIENT-SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d 'grant_type=client_credentials' \
  -d 'response_type=id_token' \
  -d 'target_customer_id=100161227' // PayPal-generated customer ID

Modify the code

Copy the code sample and modify it as follows:

Change CLIENT-ID to your client ID.
Change CLIENT-SECRET to your client secret.
Change BN-CODE to your PayPal attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
Change AUTH-ASSERTION-JWT to your PayPal auth assertion token.

Merchant (returning payer)

A payer wants to use a saved payment method.

Pass the id_token into the POST body target_customer_id parameter. The target_customer_id is a unique customer ID generated when a payment_source is saved to the vault. The target_customer_id is available when capturing an order or retrieving saved payment information.

Note: Pass the customer identifier generated by PayPal, not the one you use to identify the customer in your system.

Sample server-side user ID token request with a customer ID

curl -s -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -u 'CLIENT-ID:CLIENT-SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d 'grant_type=client_credentials' \
  -d 'response_type=id_token' \
  -d 'target_customer_id=100161227' // PayPal-generated customer ID

Modify the code

Copy the code sample and modify it as follows:

Change CLIENT-ID to your client ID.
Change CLIENT-SECRET to your client secret.
Change BN-CODE to your PayPal attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
Change AUTH-ASSERTION-JWT to your PayPal auth assertion token.
Change CUSTOMER-ID to the PayPal-generated customer ID.

2. Pass user ID token to JavaScript SDK

Merchant

Pass the id_token into the JavaScript SDK through the data-user-id-token.

<script src="https://www.paypal.com/sdk/js?client-id={CLIENT-ID}&merchant-id={MERCHANT-ID}" data-user-id-token={ID-TOKEN}></script>

Modify the code

Copy the code sample and modify it as follows:

Change CLIENT-ID to your client ID.
Change MERCHANT-ID to your merchant ID.
Change ID-TOKEN to the id_token returned in the previous step

3. Add checkbox for payers to save card

Merchant and Platform

Add a checkbox element grouped with your card collection fields to give payers the option to save their card.

<div>
  <input type="checkbox" id="save" name="save">
  <label for="save">Save your card</label>
</div>

4. Pass checkbox value

Merchant and Platform

Pass document.querySelector('#save').checked to your server with the following details in the createOrder() method:

Value of the checkbox
Card name
Billing address

No verification

const cardFields = paypal.CardFields({
  createOrder: (data) => {
    // Create the order on your server and return the order ID
    const saveCheckbox = document.getElementById("save");
    return fetch("/api/paypal/order/create/", {
      method: "POST",
      body: JSON.stringify({
        // Include the saveCheckbox.checked value
        // Optionally, include the card name and billing address
      }),
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Return the order ID that was created on your server
      return orderData.id;
    });
  },
  onApprove: function (data) {
    // Authorize or capture the order on your server
    const { orderID } = data;
    return fetch(`/api/paypal/orders/${orderID}/capture/`, {
      method: "POST"
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Retrieve vault details from the response
      const vault = orderData?.paymentSource?.card?.attributes?.vault;
      if (vault) {
        // Save the vault.id and vault.customer.id for future use
      }
      // Handle successful transaction
    });
  },
  onError: function (error) {
    // Handle any error that may occur
  }
});
if (cardFields.isEligible()) {
  cardFields.NameField().render("#card-name-field-container");
  cardFields.NumberField().render("#card-number-field-container");
  cardFields.ExpiryField().render("#card-expiry-field-container");
  cardFields.CVVField().render("#card-cvv-field-container");
} else {
  // Handle the workflow when credit and debit cards are not available
}
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", () => {
  cardFields.submit().then(() => {
    // Handle successful transaction
  }).catch((error) => {
    // Handle any error that may occur
  });
});

3D Secure

To trigger 3D Secure, pass the required contingency with the verification method in the create orders payload. The verification method can be contingencies parameter with SCA_ALWAYS or SCA_WHEN_REQUIRED.

SCA_ALWAYS triggers an authentication for every transaction, while SCA_WHEN_REQUIRED triggers an authentication only when a regional compliance mandate such as PSD2 is required. 3D Secure is supported only in countries with a PSD2 compliance mandate.

const cardFields = paypal.CardFields({
  createOrder: (data) => {
    // Create the order on your server and return the order ID
    const saveCheckbox = document.getElementById("save");
    return fetch("/api/paypal/order/create/", {
      method: "POST",
      body: JSON.stringify({
        // Include the saveCheckbox.checked value
        // Optionally, include the card name and billing address
        // Pass in the 3DS contingency as a verification attribute along with the payment source
        ...
          card: {
            attributes: {
              verification: {
                        method: "SCA_ALWAYS",//SCA_WHEN_REQUIRED is another option for the verification method
                    },
                },
            experience_context: {
                shipping_preference: "NO_SHIPPING",
                return_url: "https://example.com/returnUrl",
                cancel_url: "https://example.com/cancelUrl",
              },
            },
      }),
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Return the order ID that was created on your server
      return orderData.id;
    });
  },
  onApprove: function (data) {
    // Authorize or capture the order on your server
    const { liabilityshift, orderID } = data;
      if(liabilityShift) {
         /* Handle liability shift. More information in the response parameters */
        }
    return fetch(`/api/paypal/orders/${orderID}/capture/`, {
      method: "POST"
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Retrieve vault details from the response
      const vault = orderData?.paymentSource?.card?.attributes?.vault;
      if (vault) {
        // Save the vault.id and vault.customer.id for future use
      }
      // Handle successful transaction
    });
  },
  onError: function (error) {
    // Handle any error that may occur
  },
  onCancel: function () {
    // Manage presentment when customer closes 3DS verification modal
  }
});
if (cardFields.isEligible()) {
  cardFields.NameField().render("#card-name-field-container");
  cardFields.NumberField().render("#card-number-field-container");
  cardFields.ExpiryField().render("#card-expiry-field-container");
  cardFields.CVVField().render("#card-cvv-field-container");
} else {
  // Handle the workflow when credit and debit cards are not available
}
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", () => {
  cardFields.submit().then(() => {
    // Handle successful transaction
  }).catch((error) => {
    // Handle any error that may occur
  });
});

5. Create order and save card

Merchant and Platform

Server side

Set up your server to call the Create Order API. The button that the payer selects determines the payment_source sent in the following sample.

This SDK uses the Orders v2 API to save payment methods in the background. Use the following request using the Orders API to add attributes needed to save a card.

First-time payer

Save payment method for first-time payers

This request is for payers who:

Don't have a payment source saved into the vault.
Selected the save checkbox. The document.querySelector('#save').checked value is true.

To run 3D Secure on the card, set the payment_source.card.attributes.verification.method to SCA_ALWAYS or SCA_WHEN_REQUIRED.

Note : In the following requests, the payment_source.attributes.vault.store_in_vault with the value ON_SUCCESS means the card is saved with a successful authorization or capture.

Note: In the following requests, the payment_source.attributes.vault.store_in_vault with the value ON_SUCCESS means the card is saved with a successful authorization or capture.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d '{
      "intent": "CAPTURE",
      "purchase_units": [
        {
          "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
          "amount": {
            "currency_code": "USD",
            "value": "100.00"
        }
      }
    ],
      "payment_source": {
        "card": {
          "name": "Firstname Lastname",
          "billing_address": {
            "address_line_1": "123 Main St.",
            "address_line_2": "Unit B",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "12345",
            "country_code": "US"
          },
          "attributes": {
            "vault": {
              "store_in_vault": "ON_SUCCESS"
            },
            "verification": {
              "method:" "SCA_ALWAYS"
            }
          }
        }
      }
   }'

Response

Pass the order id to the JavaScript SDK. The SDK updates the order with the new card details. PayPal handles any PCI compliance issues.

After the SDK is updated, it triggers the onApprove() method, which receives an object containing the orderID. You can authorize or capture the order when you have the orderID.

Note: The request to save the payment method is made when the order is created through payment_source.attributes.vault.store_in_vault. Vault details are available only after an order is authorized or captured.

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "intent": "CAPTURE",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last-digits": "1881",
      "billing_address": {
        "address_line_1": "123 Main St.",
        "address_line_2": "Unit B",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "12345",
        "country_code": "US"
      }
    }
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ],
  "create_time": "2021-10-28T21:18:49Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Returning payer

Save payment method for returning payers

This request is for payers who:

Already have a payment method saved in the vault.
Want to save another payment method to the vault.
Selected the save checkbox. The document.getElementById("save").checked value is true.

Pass the PayPal-generated customer.id as part of this request. Link additional payment_sources to this customer through their customer.id. The customer.id is returned in the response from an authorize or capture request.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [
      {
        "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        }
      }
    ],
    "payment_source": {
      "card": {
        "name": "Firstname Lastname",
        "billing_address": {
          "address_line_1": "123 Main Street",
          "address_line_2": "Unit B",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "12345",
          "country_code": "US"
        },
        "attributes": {
          "customer": {
            "id": "100161227" // PayPal-generated customer ID
          },
          "vault": {
            "store_in_vault": "ON_SUCCESS"
          }
        }
      }
    }
  }'

Response

Pass the order id to the JavaScript SDK. The SDK updates the order with the new card details. PayPal handles any PCI compliance issues.

After the SDK is updated, it triggers the onApprove() method, which receives an object containing the orderID. You can authorize or capture the order when you have the orderID.

Note: The request to save the payment method is made when the order is created through payment_source.attributes.vault.store_in_vault. Vault details are available only after an order is authorized or captured.

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "intent": "CAPTURE",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last-digits": "1881",
      "billing_address": {
        "address_line_1": "123 Main St.",
        "address_line_2": "Unit B",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "12345",
        "country_code": "US"
      }
    }
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ],
  "create_time": "2021-10-28T21:18:49Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

6. Authorize or capture order and save card

Merchant and Platform

Server side

Set up your server to call the v2 Orders API:

Call the authorize order endpoint if the intent passed was AUTHORIZE.
Call the capture order endpoint if the intent passed was CAPTURE.

Authorize or capture order request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d '{}'

Response

{
  "id": "6XH94174N5355381V",
  "intent": "CAPTURE",
  "status": "COMPLETED",
  "payment_source": {
    "card": {
      "last_digits": "1881",
      "brand": "VISA",
      "type": "UNKNOWN",
      "attributes": {
        "vault": {
          "id": "1j4a89ge",
          "status": "VAULTED",
          "customer": {
            "id": "100161227"
          },
          "links": [
            {
              "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/1j4a89ge",
              "rel": "self",
              "method": "GET"
            },
            {
              "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/1j4a89ge",
              "rel": "delete",
              "method": "DELETE"
            },
            {
              "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6XH94174N5355381V",
              "rel": "up",
              "method": "GET"
            }
          ]
        }
      }
    }
  },
  "purchase_units": [
    {
      "reference_id": "5a69b6e3-1916-4269-87b9-358516da5102",
      "amount": {
        "currency_code": "USD",
        "value": "101.00"
      },
      "payee": {
        "email_address": "[email protected]",
        "merchant_id": "BADP95SC2GDE6"
      },
      "soft_descriptor": "PP*TEST STORE",
      "payments": {
        "captures": [
          {
            "id": "9J594045WV338432T",
            "status": "COMPLETED",
            "amount": {
              "currency_code": "USD",
              "value": "101.00"
            },
            "final_capture": true,
            "disbursement_mode": "INSTANT",
            "seller_protection": {
              "status": "NOT_ELIGIBLE"
            },
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "USD",
                "value": "101.00"
              },
              "paypal_fee": {
                "currency_code": "USD",
                "value": "3.11"
              },
              "net_amount": {
                "currency_code": "USD",
                "value": "97.89"
              }
            },
            "links": [
              {
                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9J594045WV338432T",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9J594045WV338432T/refund",
                "rel": "refund",
                "method": "POST"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6XH94174N5355381V",
                "rel": "up",
                "method": "GET"
              }
            ],
            "create_time": "2022-09-23T20:17:31Z",
            "update_time": "2022-09-23T20:17:31Z",
            "processor_response": {
              "avs_code": "A",
              "cvv_code": "M",
              "response_code": "0000"
            }
          }
        ]
      }
    }
  ],
  "create_time": "2022-09-23T20:17:31Z",
  "update_time": "2022-09-23T20:17:31Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6XH94174N5355381V",
      "rel": "self",
      "method": "GET"
    }
  ]
}

In the response from the Authorize or Capture request, the Orders v2 API interacts with the Payment Method Tokens v3 API to save the card.

The payment_source.card.attributes.vault stores the card information as the vault.id, which can be used for future payments when the vault.status is VAULTED.

Save approved payment source

If the payment has been authorized or captured, the payer doesn't need to be present to save a payment_source. To keep checkout times as short as possible, the Orders API responds as soon as payment is captured.

If the attributes.vault.status returned after payment is APPROVED, you won't have a vault.id yet. An example of the attributes object from this scenario is in the following sample:

"attributes": {
    "vault": {
      "status": "APPROVED",
      "links": []
    }
  }

The Payment Method Tokens API still saves the payment source even after the Orders API returns its response and sends a webhook after the payment source is saved.

In order to retrieve a vault_id when an APPROVED status is returned, you'll need to subscribe to the VAULT.PAYMENT-TOKEN.CREATED webhook.

The Payment Method Tokens API sends a webhook after the payment source is saved. An example of the VAULT.PAYMENT-TOKEN.CREATED webhook payload is shown in the following sample:

{
  "id": "WH-1KN88282901968003-82E75604WM969463F",
  "event_version": "1.0",
  "create_time": "2022-08-15T14:13:48.978Z",
  "resource_type": "payment_token",
  "resource_version": "3.0",
  "event_type": "VAULT.PAYMENT-TOKEN.CREATED",
  "summary": "A payment token has been created.",
  "resource": {
    "time_created": "2022-08-15T07:13:48.964PDT",
    "links": [
      {
        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/9n6724m",
        "rel": "self",
        "method": "GET",
        "encType": "application/json"
      },
      {
        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/9n6724m",
        "rel": "delete",
        "method": "DELETE",
        "encType": "application/json"
      }
    ],
    "id": "nkq2y9g",
    "payment_source": {
      "card": {
        "last_digits": "1111",
        "brand": "VISA",
        "expiry": "2027-02",
        "billing_address": {
          "address_line_1": "123 Main St.",
          "address_line_2": "Unit B",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "12345",
          "country_code": "US"
        }
      }
    },
    "customer": {
      "id": "695922590"
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-1KN88282901968003-82E75604WM969463F",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-1KN88282901968003-82E75604WM969463F/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

In this example, the resource.id field is the vault ID, and resource.customer.id is the PayPal-generated customer ID.

You can now style your card fields and test a purchase.

Payment processor codes

Payment processors return the following codes when they receive a transaction request. For advanced card payments, the code displays in the authorization object under the response_code field.

The following sample shows the processor response codes returned in an authorization (avs_code) and capture call (cvv_code) response:

"processor_response": {
    "avs_code": "Y",
    "cvv_code": "S",
    "response_code": "0000"
  }

See the Orders API response_code object to get the processor response code for the non-PayPal payment processor errors.

7. Pay with saved payment methods

Merchant and Platform

When a payer returns to your site, you can show the payer's saved payment methods with the Payment Method Tokens API.

Create UI

Create your own UI to show saved payment methods for returning payers.

List all saved payment methods

Make the server-side list all payment tokens API call to retrieve payment methods saved to a payer's PayPal-generated customer ID. Based on this list, you can show all saved payment methods to a payer to select during checkout.

curl -L -X GET https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=100161227 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -H 'Accept-Language: en_US'

Show saved card to payer

Display the saved card to the payer and use the Orders API to make another transaction. Use the vault ID the payer selects as an input to the Orders API to capture the payment.

Use supported CSS properties to style the card fields.

curl -L -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Accept: application/json' \
  -H 'Accept-Language: en_US' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -H 'PayPal-Request-Id: PAYPAL-REQUEST-ID' \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [
      {
        "amount": {
          "currency_code": "USD",
          "value": "50.00"
        }
      }
    ],
    "payment_source": {
      "card": {
        "vault_id": "1j4a89ge"
      }
    }
  }'

Integrate front end

The following sample shows how a full script to save cards might appear in HTML:

<!DOCTYPE html>
<html>

<head>
    <!-- Add meta tags for mobile and IE -->
    <meta charset="utf-8" />
</head>

<body>
    <script
        src="https://www.paypal.com/sdk/js?components=card-fields&client-id=YOUR-CLIENT-ID&currency=USD&intent=capture&merchant-id=YOUR-MERCHANT-ID"></script>
    <div> or </div>
    <!-- Advanced credit and debit card payments form -->
    <div class='card_container'>
        <div id='card-number'></div>
        <div id='expiration-date'></div>
        <div id='cvv'></div>
        <div id='card-holder-name'></div>
        <label>
            <input type='checkbox' id='vault' name='vault' /> Vault
        </label>
        <br><br>
        <button value='submit' id='submit' class='btn'>Pay</button>
    </div>
    <!-- Implementation -->
    <script>
        // Create the card fields component and define callbacks
        const cardFields = paypal.CardFields({
            createOrder: async (data) => {
                const result = await fetch("https://api-m.sandbox.paypal.com/v2/checkout/orders", {
                    method: "POST",
                    body: JSON.stringify({
                        intent: "CAPTURE",
                        purchase_units: [{
                            amount: {
                                currency_code: "USD",
                                value: "100.00"
                            }
                        }],
                        payment_source: {
                            card: {
                                attributes: {
                                    verification: {
                                        method: "SCA_ALWAYS"
                                    },
                                    vault: {
                                        store_in_vault: "ON_SUCCESS",
                                        usage_type: "PLATFORM",
                                        customer_type: "CONSUMER",
                                        permit_multiple_payment_tokens: true,
                                    },
                                }
                            },
                            experience_context: {
                                shipping_preference: "NO_SHIPPING",
                                return_url: "https://example.com/returnUrl",
                                cancel_url: "https://example.com/cancelUrl",
                            },
                        },
                    }),
                    headers: {
                         "Content-Type": "application/json",
                         "Authorization": "Bearer ACCESS-TOKEN",
                         "PayPal-Partner-Attribution-Id": "BN-CODE",
                         "PayPal-Auth-Assertion-Id": "AUTH-ASSERTION-JWT",
                         "PayPal-Request-Id": "REQUEST-ID",
                    },
                })
                const {
                    id
                } = await result.json();
                return id;
            },
            onApprove: async (data) => {
                const {
                    orderID
                } = data;
                return fetch('https://api-m.sandbox.paypal.com/v2/checkout/orders/${orderID}/capture/', {
                    method: "POST",
                    body: JSON.stringify({
                        payment_source: {
                            attributes: {
                                vault: {
                                    store_in_vault: "ON_SUCCESS",
                                    usage_type: "PLATFORM",
                                    customer_type: "CONSUMER",
                                    permit_multiple_payment_tokens: true,
                                },
                            },
                            experience_context: {
                                shipping_preference: "NO_SHIPPING",
                                return_url: "https://example.com/returnUrl",
                                cancel_url: "https://example.com/cancelUrl",
                            },
                        },
                    }),
                    headers: {
                         "Content-Type": "application/json",
                         "Authorization": "Bearer ACCESS-TOKEN",
                         "PayPal-Partner-Attribution-Id": "BN-CODE",
                         "PayPal-Auth-Assertion-Id": "AUTH-ASSERTION-JWT",
                         "PayPal-Request-Id": "REQUEST-ID",
                    },
                })
                // Retrieve vault details from the response and
                // save vault.id and customer.id for the buyer's return experience
                return await res.json();
            },
            onError: (error) => console.error('Something went wrong:', error)
        });
        // Render each field after checking for eligibility
        // Check eligibility and display advanced credit and debit card payments
        if (cardFields.isEligible()) {
            cardFields.NameField().render("#card-holder-name");
            cardFields.NumberField().render("#card-number");
            cardFields.ExpiryField().render("#expiration-date");
            cardFields.CVVField().render("#cvv");
        } else {
            // Handle workflow when credit and debit cards are not available
        }
        const submitButton = document.getElementById("submit");
        submitButton.addEventListener("click", () => {
            cardFields
                .submit()
                .then(() => {
                    console.log("submit was successful");
                })
                .catch((error) => {
                    console.error("submit erred:", error);
                });
        });
    </script>
</body>

</html>

Test cards

Use the following card numbers to test transactions in the sandbox:

Test number, Card type
Test number	Card type
371449635398431	American Express
376680816376961	American Express
36259600000004	Diners Club
6304000000000000	Maestro
5063516945005047	Maestro
2223000048400011	Mastercard
4005519200000004	Visa
4012000033330026	Visa
4012000077777777	Visa
4012888888881881	Visa
4217651111111119	Visa
4500600000000061	Visa
4772129056533503	Visa
4915805038587737	Visa

Next steps

Test and go live with this integration.
- Change the credentials and API URL from sandbox to your live environment when going live with your integration.
Use payment method token with checkout for subsequent or recurring transactions.
You can get a payment token, list all payment tokens, delete a payment token, and more with the Payment Method Tokens API.

Know before you code

This integration requires a PayPal Developer account.
You'll need to have an existing advanced credit and debit card payments integration. PayPal must approve your account to process advanced credit and debit card payments.
Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:
- The sandbox client ID and secret of your REST app.
- An access token to use the PayPal REST API server.
This client-side and server-side integration uses the following:
- PayPal JavaScript SDK
- Orders REST API

How it works

PayPal encrypts payment method information and stores it in a digital vault for that customer.

The payer saves their payment method.
For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
When the customer returns to your website and is ready to check out, pass their PayPal-generated customer ID to the JavaScript SDK. The customer ID tells the JavaScript SDK to save or reuse a saved payment method.
The payer completes a billing agreement.
The JavaScript SDK populates the checkout page with each saved payment method. Each payment method appears as a one-click button next to other ways to pay.

The checkout process is now shorter because it uses saved payment information.

Use cases

Businesses save payment methods if they want customers to:

Check out without re-entering a payment method
Pay after use, for example, ride-sharing and food delivery

Select platform or merchant

If you're a third-party saving payment method on behalf of merchants, select Merchant (see steps 1-7).

If you're a platform for hosting merchants, select Platform(see steps 3-7).

1. Generate user ID token for payer

Merchant (first-time payer)

A payer wants to save a payment method for the first time.

The PayPal OAuth 2.0 API has a response_type parameter. Set the response_type to id_token to retrieve a unique ID token for a payer when a payer saves a new payment method.

Sample server-side user ID token request

curl -s -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -u 'CLIENT-ID:CLIENT-SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d 'grant_type=client_credentials' \
  -d 'response_type=id_token' \
  -d 'target_customer_id=100161227' // PayPal-generated customer ID

Modify the code

Copy the code sample and modify it as follows:

Change CLIENT-ID to your client ID.
Change CLIENT-SECRET to your client secret.
Change BN-CODE to your PayPal attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
Change AUTH-ASSERTION-JWT to your PayPal auth assertion token.

Merchant (returning payer)

A payer wants to use a saved payment method.

Note: Pass the customer identifier generated by PayPal, not the one you use to identify the customer in your system.

Sample server-side user ID token request with a customer ID

curl -s -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -u 'CLIENT-ID:CLIENT-SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d 'grant_type=client_credentials' \
  -d 'response_type=id_token' \
  -d 'target_customer_id=100161227' // PayPal-generated customer ID

Modify the code

Copy the code sample and modify it as follows:

Change CLIENT-ID to your client ID.
Change CLIENT-SECRET to your client secret.
Change BN-CODE to your PayPal attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
Change AUTH-ASSERTION-JWT to your PayPal auth assertion token.
Change CUSTOMER-ID to the PayPal-generated customer ID.

2. Pass user ID token to JavaScript SDK

Merchant

Pass the id_token into the JavaScript SDK through the data-user-id-token.

<script src="https://www.paypal.com/sdk/js?client-id={CLIENT-ID}&merchant-id={MERCHANT-ID}" data-user-id-token={ID-TOKEN}></script>

Modify the code

Copy the code sample and modify it as follows:

Change CLIENT-ID to your client ID.
Change MERCHANT-ID to your merchant ID.
Change ID-TOKEN to the id_token returned in the previous step

3. Add checkbox for payers to save card

Merchant and Platform

Add a checkbox element grouped with your card collection fields to give payers the option to save their card.

<div>
  <input type="checkbox" id="save" name="save">
  <label for="save">Save your card</label>
</div>

4. Pass checkbox value

Merchant and Platform

Pass document.querySelector('#save').checked to your server with the following details in the createOrder() method:

Value of the checkbox
Card name
Billing address

No verification

const cardFields = paypal.CardFields({
  createOrder: (data) => {
    // Create the order on your server and return the order ID
    const saveCheckbox = document.getElementById("save");
    return fetch("/api/paypal/order/create/", {
      method: "POST",
      body: JSON.stringify({
        // Include the saveCheckbox.checked value
        // Optionally, include the card name and billing address
      }),
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Return the order ID that was created on your server
      return orderData.id;
    });
  },
  onApprove: function (data) {
    // Authorize or capture the order on your server
    const { orderID } = data;
    return fetch(`/api/paypal/orders/${orderID}/capture/`, {
      method: "POST"
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Retrieve vault details from the response
      const vault = orderData?.paymentSource?.card?.attributes?.vault;
      if (vault) {
        // Save the vault.id and vault.customer.id for future use
      }
      // Handle successful transaction
    });
  },
  onError: function (error) {
    // Handle any error that may occur
  }
});
if (cardFields.isEligible()) {
  cardFields.NameField().render("#card-name-field-container");
  cardFields.NumberField().render("#card-number-field-container");
  cardFields.ExpiryField().render("#card-expiry-field-container");
  cardFields.CVVField().render("#card-cvv-field-container");
} else {
  // Handle the workflow when credit and debit cards are not available
}
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", () => {
  cardFields.submit().then(() => {
    // Handle successful transaction
  }).catch((error) => {
    // Handle any error that may occur
  });
});

3D Secure

const cardFields = paypal.CardFields({
  createOrder: (data) => {
    // Create the order on your server and return the order ID
    const saveCheckbox = document.getElementById("save");
    return fetch("/api/paypal/order/create/", {
      method: "POST",
      body: JSON.stringify({
        // Include the saveCheckbox.checked value
        // Optionally, include the card name and billing address
        // Pass in the 3DS contingency as a verification attribute along with the payment source
        ...
          card: {
            attributes: {
              verification: {
                        method: "SCA_ALWAYS",//SCA_WHEN_REQUIRED is another option for the verification method
                    },
                },
            experience_context: {
                shipping_preference: "NO_SHIPPING",
                return_url: "https://example.com/returnUrl",
                cancel_url: "https://example.com/cancelUrl",
              },
            },
      }),
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Return the order ID that was created on your server
      return orderData.id;
    });
  },
  onApprove: function (data) {
    // Authorize or capture the order on your server
    const { liabilityshift, orderID } = data;
      if(liabilityShift) {
         /* Handle liability shift. More information in the response parameters */
        }
    return fetch(`/api/paypal/orders/${orderID}/capture/`, {
      method: "POST"
    }).then((res) => {
      return res.json();
    }).then((orderData) => {
      // Retrieve vault details from the response
      const vault = orderData?.paymentSource?.card?.attributes?.vault;
      if (vault) {
        // Save the vault.id and vault.customer.id for future use
      }
      // Handle successful transaction
    });
  },
  onError: function (error) {
    // Handle any error that may occur
  },
  onCancel: function () {
    // Manage presentment when customer closes 3DS verification modal
  }
});
if (cardFields.isEligible()) {
  cardFields.NameField().render("#card-name-field-container");
  cardFields.NumberField().render("#card-number-field-container");
  cardFields.ExpiryField().render("#card-expiry-field-container");
  cardFields.CVVField().render("#card-cvv-field-container");
} else {
  // Handle the workflow when credit and debit cards are not available
}
const submitButton = document.getElementById("submit-button");
submitButton.addEventListener("click", () => {
  cardFields.submit().then(() => {
    // Handle successful transaction
  }).catch((error) => {
    // Handle any error that may occur
  });
});

5. Create order and save card

Merchant and Platform

Server side

Set up your server to call the Create Order API. The button that the payer selects determines the payment_source sent in the following sample.

This SDK uses the Orders v2 API to save payment methods in the background. Use the following request using the Orders API to add attributes needed to save a card.

First-time payer

Save payment method for first-time payers

This request is for payers who:

Don't have a payment source saved into the vault.
Selected the save checkbox. The document.querySelector('#save').checked value is true.

To run 3D Secure on the card, set the payment_source.card.attributes.verification.method to SCA_ALWAYS or SCA_WHEN_REQUIRED.

Note : In the following requests, the payment_source.attributes.vault.store_in_vault with the value ON_SUCCESS means the card is saved with a successful authorization or capture.

Note: In the following requests, the payment_source.attributes.vault.store_in_vault with the value ON_SUCCESS means the card is saved with a successful authorization or capture.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d '{
      "intent": "CAPTURE",
      "purchase_units": [
        {
          "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
          "amount": {
            "currency_code": "USD",
            "value": "100.00"
        }
      }
    ],
      "payment_source": {
        "card": {
          "name": "Firstname Lastname",
          "billing_address": {
            "address_line_1": "123 Main St.",
            "address_line_2": "Unit B",
            "admin_area_2": "Anytown",
            "admin_area_1": "CA",
            "postal_code": "12345",
            "country_code": "US"
          },
          "attributes": {
            "vault": {
              "store_in_vault": "ON_SUCCESS"
            },
            "verification": {
              "method:" "SCA_ALWAYS"
            }
          }
        }
      }
   }'

Response

Pass the order id to the JavaScript SDK. The SDK updates the order with the new card details. PayPal handles any PCI compliance issues.

After the SDK is updated, it triggers the onApprove() method, which receives an object containing the orderID. You can authorize or capture the order when you have the orderID.

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "intent": "CAPTURE",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last-digits": "1881",
      "billing_address": {
        "address_line_1": "123 Main St.",
        "address_line_2": "Unit B",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "12345",
        "country_code": "US"
      }
    }
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ],
  "create_time": "2021-10-28T21:18:49Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Returning payer

Save payment method for returning payers

This request is for payers who:

Already have a payment method saved in the vault.
Want to save another payment method to the vault.
Selected the save checkbox. The document.getElementById("save").checked value is true.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [
      {
        "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        }
      }
    ],
    "payment_source": {
      "card": {
        "name": "Firstname Lastname",
        "billing_address": {
          "address_line_1": "123 Main Street",
          "address_line_2": "Unit B",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "12345",
          "country_code": "US"
        },
        "attributes": {
          "customer": {
            "id": "100161227" // PayPal-generated customer ID
          },
          "vault": {
            "store_in_vault": "ON_SUCCESS"
          }
        }
      }
    }
  }'

Response

Pass the order id to the JavaScript SDK. The SDK updates the order with the new card details. PayPal handles any PCI compliance issues.

After the SDK is updated, it triggers the onApprove() method, which receives an object containing the orderID. You can authorize or capture the order when you have the orderID.

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "intent": "CAPTURE",
  "payment_source": {
    "card": {
      "brand": "VISA",
      "last-digits": "1881",
      "billing_address": {
        "address_line_1": "123 Main St.",
        "address_line_2": "Unit B",
        "admin_area_2": "Anytown",
        "admin_area_1": "CA",
        "postal_code": "12345",
        "country_code": "US"
      }
    }
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ],
  "create_time": "2021-10-28T21:18:49Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "update",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

6. Authorize or capture order and save card

Merchant and Platform

Server side

Set up your server to call the v2 Orders API:

Call the authorize order endpoint if the intent passed was AUTHORIZE.
Call the capture order endpoint if the intent passed was CAPTURE.

Authorize or capture order request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -d '{}'

Response

{
  "id": "6XH94174N5355381V",
  "intent": "CAPTURE",
  "status": "COMPLETED",
  "payment_source": {
    "card": {
      "last_digits": "1881",
      "brand": "VISA",
      "type": "UNKNOWN",
      "attributes": {
        "vault": {
          "id": "1j4a89ge",
          "status": "VAULTED",
          "customer": {
            "id": "100161227"
          },
          "links": [
            {
              "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/1j4a89ge",
              "rel": "self",
              "method": "GET"
            },
            {
              "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/1j4a89ge",
              "rel": "delete",
              "method": "DELETE"
            },
            {
              "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6XH94174N5355381V",
              "rel": "up",
              "method": "GET"
            }
          ]
        }
      }
    }
  },
  "purchase_units": [
    {
      "reference_id": "5a69b6e3-1916-4269-87b9-358516da5102",
      "amount": {
        "currency_code": "USD",
        "value": "101.00"
      },
      "payee": {
        "email_address": "[email protected]",
        "merchant_id": "BADP95SC2GDE6"
      },
      "soft_descriptor": "PP*TEST STORE",
      "payments": {
        "captures": [
          {
            "id": "9J594045WV338432T",
            "status": "COMPLETED",
            "amount": {
              "currency_code": "USD",
              "value": "101.00"
            },
            "final_capture": true,
            "disbursement_mode": "INSTANT",
            "seller_protection": {
              "status": "NOT_ELIGIBLE"
            },
            "seller_receivable_breakdown": {
              "gross_amount": {
                "currency_code": "USD",
                "value": "101.00"
              },
              "paypal_fee": {
                "currency_code": "USD",
                "value": "3.11"
              },
              "net_amount": {
                "currency_code": "USD",
                "value": "97.89"
              }
            },
            "links": [
              {
                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9J594045WV338432T",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9J594045WV338432T/refund",
                "rel": "refund",
                "method": "POST"
              },
              {
                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6XH94174N5355381V",
                "rel": "up",
                "method": "GET"
              }
            ],
            "create_time": "2022-09-23T20:17:31Z",
            "update_time": "2022-09-23T20:17:31Z",
            "processor_response": {
              "avs_code": "A",
              "cvv_code": "M",
              "response_code": "0000"
            }
          }
        ]
      }
    }
  ],
  "create_time": "2022-09-23T20:17:31Z",
  "update_time": "2022-09-23T20:17:31Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6XH94174N5355381V",
      "rel": "self",
      "method": "GET"
    }
  ]
}

In the response from the Authorize or Capture request, the Orders v2 API interacts with the Payment Method Tokens v3 API to save the card.

The payment_source.card.attributes.vault stores the card information as the vault.id, which can be used for future payments when the vault.status is VAULTED.

Save approved payment source

If the attributes.vault.status returned after payment is APPROVED, you won't have a vault.id yet. An example of the attributes object from this scenario is in the following sample:

"attributes": {
    "vault": {
      "status": "APPROVED",
      "links": []
    }
  }

The Payment Method Tokens API still saves the payment source even after the Orders API returns its response and sends a webhook after the payment source is saved.

In order to retrieve a vault_id when an APPROVED status is returned, you'll need to subscribe to the VAULT.PAYMENT-TOKEN.CREATED webhook.

The Payment Method Tokens API sends a webhook after the payment source is saved. An example of the VAULT.PAYMENT-TOKEN.CREATED webhook payload is shown in the following sample:

{
  "id": "WH-1KN88282901968003-82E75604WM969463F",
  "event_version": "1.0",
  "create_time": "2022-08-15T14:13:48.978Z",
  "resource_type": "payment_token",
  "resource_version": "3.0",
  "event_type": "VAULT.PAYMENT-TOKEN.CREATED",
  "summary": "A payment token has been created.",
  "resource": {
    "time_created": "2022-08-15T07:13:48.964PDT",
    "links": [
      {
        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/9n6724m",
        "rel": "self",
        "method": "GET",
        "encType": "application/json"
      },
      {
        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/9n6724m",
        "rel": "delete",
        "method": "DELETE",
        "encType": "application/json"
      }
    ],
    "id": "nkq2y9g",
    "payment_source": {
      "card": {
        "last_digits": "1111",
        "brand": "VISA",
        "expiry": "2027-02",
        "billing_address": {
          "address_line_1": "123 Main St.",
          "address_line_2": "Unit B",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "12345",
          "country_code": "US"
        }
      }
    },
    "customer": {
      "id": "695922590"
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-1KN88282901968003-82E75604WM969463F",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-1KN88282901968003-82E75604WM969463F/resend",
      "rel": "resend",
      "method": "POST"
    }
  ]
}

In this example, the resource.id field is the vault ID, and resource.customer.id is the PayPal-generated customer ID.

You can now style your card fields and test a purchase.

Payment processor codes

Payment processors return the following codes when they receive a transaction request. For advanced card payments, the code displays in the authorization object under the response_code field.

The following sample shows the processor response codes returned in an authorization (avs_code) and capture call (cvv_code) response:

"processor_response": {
    "avs_code": "Y",
    "cvv_code": "S",
    "response_code": "0000"
  }

See the Orders API response_code object to get the processor response code for the non-PayPal payment processor errors.

curl -L -X GET https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=100161227 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -H 'Accept-Language: en_US'

Show saved card to payer

Display the saved card to the payer and use the Orders API to make another transaction. Use the vault ID the payer selects as an input to the Orders API to capture the payment.

Use supported CSS properties to style the card fields.

curl -L -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Accept: application/json' \
  -H 'Accept-Language: en_US' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
  -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
  -H 'PayPal-Request-Id: PAYPAL-REQUEST-ID' \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [
      {
        "amount": {
          "currency_code": "USD",
          "value": "50.00"
        }
      }
    ],
    "payment_source": {
      "card": {
        "vault_id": "1j4a89ge"
      }
    }
  }'

Integrate front end

The following sample shows how a full script to save cards might appear in HTML:

<!DOCTYPE html>
<html>

<head>
    <!-- Add meta tags for mobile and IE -->
    <meta charset="utf-8" />
</head>

<body>
    <script
        src="https://www.paypal.com/sdk/js?components=card-fields&client-id=YOUR-CLIENT-ID&currency=USD&intent=capture&merchant-id=YOUR-MERCHANT-ID"></script>
    <div> or </div>
    <!-- Advanced credit and debit card payments form -->
    <div class='card_container'>
        <div id='card-number'></div>
        <div id='expiration-date'></div>
        <div id='cvv'></div>
        <div id='card-holder-name'></div>
        <label>
            <input type='checkbox' id='vault' name='vault' /> Vault
        </label>
        <br><br>
        <button value='submit' id='submit' class='btn'>Pay</button>
    </div>
    <!-- Implementation -->
    <script>
        // Create the card fields component and define callbacks
        const cardFields = paypal.CardFields({
            createOrder: async (data) => {
                const result = await fetch("https://api-m.sandbox.paypal.com/v2/checkout/orders", {
                    method: "POST",
                    body: JSON.stringify({
                        intent: "CAPTURE",
                        purchase_units: [{
                            amount: {
                                currency_code: "USD",
                                value: "100.00"
                            }
                        }],
                        payment_source: {
                            card: {
                                attributes: {
                                    verification: {
                                        method: "SCA_ALWAYS"
                                    },
                                    vault: {
                                        store_in_vault: "ON_SUCCESS",
                                        usage_type: "PLATFORM",
                                        customer_type: "CONSUMER",
                                        permit_multiple_payment_tokens: true,
                                    },
                                }
                            },
                            experience_context: {
                                shipping_preference: "NO_SHIPPING",
                                return_url: "https://example.com/returnUrl",
                                cancel_url: "https://example.com/cancelUrl",
                            },
                        },
                    }),
                    headers: {
                         "Content-Type": "application/json",
                         "Authorization": "Bearer ACCESS-TOKEN",
                         "PayPal-Partner-Attribution-Id": "BN-CODE",
                         "PayPal-Auth-Assertion-Id": "AUTH-ASSERTION-JWT",
                         "PayPal-Request-Id": "REQUEST-ID",
                    },
                })
                const {
                    id
                } = await result.json();
                return id;
            },
            onApprove: async (data) => {
                const {
                    orderID
                } = data;
                return fetch('https://api-m.sandbox.paypal.com/v2/checkout/orders/${orderID}/capture/', {
                    method: "POST",
                    body: JSON.stringify({
                        payment_source: {
                            attributes: {
                                vault: {
                                    store_in_vault: "ON_SUCCESS",
                                    usage_type: "PLATFORM",
                                    customer_type: "CONSUMER",
                                    permit_multiple_payment_tokens: true,
                                },
                            },
                            experience_context: {
                                shipping_preference: "NO_SHIPPING",
                                return_url: "https://example.com/returnUrl",
                                cancel_url: "https://example.com/cancelUrl",
                            },
                        },
                    }),
                    headers: {
                         "Content-Type": "application/json",
                         "Authorization": "Bearer ACCESS-TOKEN",
                         "PayPal-Partner-Attribution-Id": "BN-CODE",
                         "PayPal-Auth-Assertion-Id": "AUTH-ASSERTION-JWT",
                         "PayPal-Request-Id": "REQUEST-ID",
                    },
                })
                // Retrieve vault details from the response and
                // save vault.id and customer.id for the buyer's return experience
                return await res.json();
            },
            onError: (error) => console.error('Something went wrong:', error)
        });
        // Render each field after checking for eligibility
        // Check eligibility and display advanced credit and debit card payments
        if (cardFields.isEligible()) {
            cardFields.NameField().render("#card-holder-name");
            cardFields.NumberField().render("#card-number");
            cardFields.ExpiryField().render("#expiration-date");
            cardFields.CVVField().render("#cvv");
        } else {
            // Handle workflow when credit and debit cards are not available
        }
        const submitButton = document.getElementById("submit");
        submitButton.addEventListener("click", () => {
            cardFields
                .submit()
                .then(() => {
                    console.log("submit was successful");
                })
                .catch((error) => {
                    console.error("submit erred:", error);
                });
        });
    </script>
</body>

</html>

Test cards

Use the following card numbers to test transactions in the sandbox:

Test number, Card type
Test number	Card type
371449635398431	American Express
376680816376961	American Express
36259600000004	Diners Club
6304000000000000	Maestro
5063516945005047	Maestro
2223000048400011	Mastercard
4005519200000004	Visa
4012000033330026	Visa
4012000077777777	Visa
4012888888881881	Visa
4217651111111119	Visa
4500600000000061	Visa
4772129056533503	Visa
4915805038587737	Visa

Next steps

Test and go live with this integration.
- Change the credentials and API URL from sandbox to your live environment when going live with your integration.
Use payment method token with checkout for subsequent or recurring transactions.
You can get a payment token, list all payment tokens, delete a payment token, and more with the Payment Method Tokens API.

Save cards with the JavaScript SDK

On this page

On this page

On this page

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

Save cards with the JavaScript SDK

On this page

On this page