Save cards with the Orders API

Docs

Last updated: Oct 25th, 8:01pm

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.

Save cards with the Orders API if you want to save cards during checkout but aren't PCI Compliant - SAQ A.

Availability

List of supported countries:

  • Australia
  • Austria
  • Belgium
  • Bulgaria
  • Canada
  • China
  • Cyprus
  • Czech Republic
  • Denmark
  • Estonia
  • Finland
  • France
  • Germany
  • Hong Kong
  • Hungary
  • Ireland
  • Italy
  • Japan
  • Latvia
  • Liechtenstein
  • Lithuania
  • Luxembourg
  • Malta
  • Netherlands
  • Norway
  • Poland
  • Portugal
  • Romania
  • Singapore
  • Slovakia
  • Slovenia
  • Spain
  • Sweden
  • United Kingdom
  • United States

Know before you code

  • The Orders API supports saving PayPal and card payment methods only.
  • Passing card data to the Orders API requires you to be PCI Compliant - SAQ D.
  • Contact your account manager to configure your account to save payment methods.
  • 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.

How it works

When a payer on your website saves their payment method, PayPal creates a customer record. PayPal then encrypts the payment method information and stores it in a digital vault. The vault is accessible only by the billing agreement holder.

  1. The payer saves their payment method.
  2. For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
  3. Pass a call into the Orders API. Include the payment method, customer ID, and an indication that the payment method should be saved.
  4. If the order is processed and the payment method is saved, you receive a payment method token in the Orders API response.
  5. Pass the payment method token into the Orders API to populate the checkout page with the saved payment method.

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

Save card fields

Make a server-side API call to create the order and save the card at the same time. When a payer is using a card to check out, the Orders API can capture the payment in a single request.

Use 3D Secure authentication to reduce the likelihood of fraud and improve transaction performance with supported cards. In some countries, authorizing a card can trigger a 3D Secure contingency. 3D Secure verification may occur in PSD2 countries, including members of the EU. For 3D Secure verification, pass SCA_ALWAYS or SCA_WHEN_REQUIRED in the payment_source.card.attributes.verification.method field for the create order request. The API response returns the order status as PAYER_ACTION_REQUIRED.

Save card fields for a returning payer

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

Call the List All Payment Tokens API server-side to retrieve all payment methods saved for a payer. Identify the payer using the PayPal-generated customer.id. From this list, you can show all saved payment methods to a payer to allow them to select one during checkout.

In the following sample, the authorize and capture requests occur in a single request, and the card is stored in the vault with 3D Secure verification when required.

Platform

Modify the code

The payment_source.card.attributes.vault stores the card information as the vault.id. Use the vault.id future payments. Check the Orders API attributes.vault.status object for the following responses:

  • "VAULTED" - the vault.id is returned
  • "APPROVED" - subscribe to the VAULT.PAYMENT-TOKEN.CREATED [webhook](/api/rest/webhooks/) to receive a vault.id

Save the customer.id and vault.id values in your database.

Because 3D Secure verification wasn't required in this example, the API response doesn't return PAYER_ACTION_REQUIRED as the order status.

An "APPROVED" status from the Orders capture response is shown in the following sample:


    1"attributes": {
    2  "vault": {
    3    "status": "APPROVED",
    4    "links": [
    5      {
    6        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
    7        "rel": "up",
    8        "method": "GET"
    9      }
    10    ]
    11  }
    12}

    The card is saved. You can see the Vault Payment Token ID in the response of the Create payment token API call.

    Merchant

    First-time payer

    Sample request: create order and save card



      1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
      2 -H 'Accept: application/json' \
      3 -H 'Content-Type: application/json' \
      4 -H 'Accept-Language: en_US' \
      5 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
      6 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
      7 -H 'Authorization: Bearer ACCESS-TOKEN' \
      8 -H 'PayPal-Request-ID: 1337623214' \
      9 -d '
      10  {
      11    "intent": "CAPTURE",
      12    "payment_source": {
      13        "card": {
      14            "number": "4009348888881881",
      15            "expiry": "2024-02",
      16            "name": "Firstname Lastname",
      17            "billing_address": {
      18                "address_line_1": "2211 N First Street",
      19                "address_line_2": "Building 17",
      20                "admin_area_2": "San Jose",
      21                "admin_area_1": "CA",
      22                "postal_code": "95131",
      23                "country_code": "US"
      24            },
      25            "attributes": {
      26                "verification": {
      27                  "method": "SCA_WHEN_REQUIRED"
      28                },
      29                "vault": {
      30                    "store_in_vault": "ON_SUCCESS",
      31                }
      32            }
      33        }
      34    },
      35    "purchase_units": [
      36        {
      37            "amount": {
      38                "currency_code": "USD",
      39                "value": "101.00"
      40            }
      41        }
      42    ]
      43}'

      Sample response: create order and save card


        1{
        2  "id": "90P05900J8046300H",
        3  "status": "COMPLETED",
        4  "payment_source": {
        5    "card": {
        6      "last_digits": "1881",
        7      "brand": "VISA",
        8      "type": "CREDIT",
        9      "attributes": {
        10        "vault": {
        11          "id": "a9dczv36",
        12          "status": "VAULTED",
        13          "customer": {
        14              "id": "customer_111941532"
        15          },
        16          "links": [{
        17              "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/a9dczv36",
        18              "rel": "self",
        19              "method": "GET"
        20            },
        21            {
        22              "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/a9dczv36",
        23              "rel": "delete",
        24              "method": "DELETE"
        25            },
        26            {
        27              "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/90P05900J8046300H",
        28              "rel": "up",
        29              "method": "GET"
        30            }
        31          ]
        32        }
        33      }
        34    }
        35  },
        36  "purchase_units": [{
        37    "reference_id": "default",
        38    "payments": {
        39      "captures": [{
        40        "id": "6TX09863BM735861G",
        41        "status": "COMPLETED",
        42        "amount": {
        43          "currency_code": "USD",
        44          "value": "101.00"
        45        },
        46        "final_capture": true,
        47        "disbursement_mode": "INSTANT",
        48        "seller_protection": {
        49          "status": "NOT_ELIGIBLE"
        50        },
        51        "seller_receivable_breakdown": {
        52          "gross_amount": {
        53            "currency_code": "USD",
        54            "value": "101.00"
        55          },
        56          "paypal_fee": {
        57            "currency_code": "USD",
        58            "value": "3.11"
        59          },
        60          "net_amount": {
        61            "currency_code": "USD",
        62            "value": "97.89"
        63          }
        64        },
        65        "links": [{
        66            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/6TX09863BM735861G",
        67            "rel": "self",
        68            "method": "GET"
        69          },
        70          {
        71            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/6TX09863BM735861G/refund",
        72            "rel": "refund",
        73            "method": "POST"
        74          },
        75          {
        76            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/90P05900J8046300H",
        77            "rel": "up",
        78            "method": "GET"
        79          }
        80        ],
        81        "create_time": "2022-10-07T22:32:25Z",
        82        "update_time": "2022-10-07T22:32:25Z",
        83        "processor_response": {
        84          "avs_code": "A",
        85          "cvv_code": "M",
        86          "response_code": "0000"
        87        }
        88      }]
        89    }
        90  }],
        91  "links": [{
        92    "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/90P05900J8046300H",
        93    "rel": "self",
        94    "method": "GET"
        95  }]
        96}

        Returning Payer

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

        Call the List All Payment Tokens API server-side to retrieve all payment methods saved for a payer. Identify the payer using the PayPal-generated customer.id. Use the response of the Payment Method Tokens API to present the payer with a list of their saved payment methods. The payer can choose which payment method to use during checkout.

        Sample request: list all payment tokens

          1curl --location --request GET 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=CUSTOMER-ID' \
          2 -H 'Content-Type: application/json' \
          3 -H 'Accept-Language: en_US' \
          4 -H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION' \
          5 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
          6 -H 'Authorization: Bearer ACCESS-TOKEN'

          Sample response


            1{
            2    "customer": {
            3        "id": "100161227"
            4    },
            5    "payment_tokens": [{
            6        "id": "1j4a89ge",
            7        "customer": {
            8            "id": "customer_100161227"
            9        },
            10        "payment_source": {
            11            "card": {
            12                "last_digits": "1881",
            13                "brand": "VISA",
            14                "expiry": "2027-04",
            15                "billing_address": {
            16                    "address_line_1": "2211 N First Street",
            17                    "address_line_2": "Building 17",
            18                    "admin_area_2": "San Jose",
            19                    "admin_area_1": "CA",
            20                    "postal_code": "95131",
            21                    "country_code": "US"
            22                },
            23                "verification_status": "NOT_VERIFIED"
            24            }
            25        },
            26        "links": [{
            27            "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/1j4a89ge",
            28            "rel": "self",
            29            "method": "GET",
            30            "encType": "application/json"
            31        }, {
            32            "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/1j4a89ge",
            33            "rel": "delete",
            34            "method": "DELETE",
            35            "encType": "application/json"
            36        }]
            37    }],
            38    "links": [{
            39        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?pageNumber=1&totalRequired=false&customer_id=100161227&pageSizeInternal=5",
            40        "rel": "self",
            41        "method": "GET",
            42        "encType": "application/json"
            43    }, {
            44        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?pageNumber=1&totalRequired=false&customer_id=100161227&pageSizeInternal=5",
            45        "rel": "first",
            46        "method": "GET",
            47        "encType": "application/json"
            48    }, {
            49        "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?pageNumber=1&totalRequired=false&customer_id=100161227&pageSizeInternal=5",
            50        "rel": "last",
            51        "method": "GET",
            52        "encType": "application/json"
            53    }]
            54}

            Modify the code

            The payment_source.card.attributes.vault stores the card information as the vault.id. Use the vault.id future payments. Check the Orders API attributes.vault.status object for the following responses:

            • "VAULTED" - the vault.id is returned
            • "APPROVED" - subscribe to the VAULT.PAYMENT-TOKEN.CREATED [webhook](/api/rest/webhooks/) to receive a vault.id

            Save the customer.id and vault.id values in your database.

            Because 3D Secure verification wasn't required in this example, the API response doesn't return PAYER_ACTION_REQUIRED as the order status.

            An "APPROVED" status from the Orders capture response is shown in the following sample:


              1"attributes": {
              2  "vault": {
              3    "status": "APPROVED",
              4    "links": [
              5      {
              6        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
              7        "rel": "up",
              8        "method": "GET"
              9      }
              10    ]
              11  }
              12}

              The card is saved. You can see the Vault Payment Token ID in the response of the Create payment token API call.

              Webhooks for saving payment methods

              Event Trigger Payment methods
              VAULT.PAYMENT-TOKEN.CREATED A payment token is created to save a payment method. Cards and PayPal
              VAULT.PAYMENT-TOKEN.DELETED A payment token is deleted. The payer's payment method is no longer saved to the PayPal vault. Cards and PayPal
              VAULT.PAYMENT-TOKEN.DELETION-INITIATED A request to delete a payment token has been submitted to the Payment Method Tokens API. PayPal

              For more information on webhooks, see webhooks.

              See also

              ReferencePayPal.comPrivacyCookiesSupportLegalContact

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