Save PayPal with the Orders API

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

You can use the Orders API to create a transaction and then save the payer's PayPal Wallet.

Save PayPal with the Orders API if you haven't integrated with a PayPal client-side JavaScript SDK, but want to save the payer's PayPal Wallet during checkout.

Important: Don't save PayPal as a payment method during purchase. For more information about securely saving payment methods and optimizing the buyer experience, see our Best practices guide.

Availability

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.
You must be approved to enable a reference transaction if you want to save PayPal as a payment source. Contact your account manager for details.

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.

The payer saves their payment method.
For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
Pass a call into the Orders API. Include the payment method, customer ID, and an indication that the payment method should be saved.
If the order is processed and the payment method is saved, you receive a payment method token in the Orders API response.
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.

PayPal requires Risk Data Acquisition (RDA) to reduce fraud. You must implement risk data collection for all customer-initiated transactions (CIT) that use PayPal and Venmo Payment Tokens. Payment attempts that are missing RDA data are likely to be declined due to insufficient risk identifiers. Use the PayPal FraudNet and Magnes libraries to collect and pass RDA data during payment processing.

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. In the following sample, the payment_source is paypal. The vault parameters in the request save the payment_source for future use by the payer.

The merchant_customer_id is an optional field that can be used to store your customer identifier information in PayPal. After a successful payment capture, the API response will return the merchant_customer_id information.

Create order and save payment

Platform

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-Request-ID: 1337623214" \
 -d '{
        "intent": "CAPTURE",
        "payment_source": {
        "paypal": {
          "attributes": {
            "customer": {
              "merchant_customer_id": "customer@example.com"
            },
            "vault": {
              "store_in_vault": "ON_SUCCESS",
              "usage_type": "PLATFORM"
            }
          },
          "experience_context": {
            "return_url": "https://example.com/returnUrl",
            "cancel_url": "https://example.com/cancelUrl"
        }
      }
    },
      "purchase_units": [{
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        },
        "payee": {
          "merchant_id": "MERCHANT-ID"
        }
      }]
    }'

Note the status of the response. Some payment sources need payer approval before payment. If so, return the id back to your client to redirect the payer to a flow where they approve the payment method.

Merchant

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-Auth-Assertion: AUTH-ASSERTION-TOKEN' \
-H 'PayPal-Partner-Attribution-ID: BN-CODE' \
-H "PayPal-Request-ID: 1337623214" \
-d '{
  "intent": "CAPTURE",
  "payment_source": {
    "paypal": {
      "attributes": {
        "customer": {
          "merchant_customer_id": "customer@example.com"
        },
        "vault": {
          "store_in_vault": "ON_SUCCESS",
          "usage_type": "MERCHANT"
        }
      },
      "experience_context": {
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl"
      }
    }
  },
  "purchase_units": [{
    "amount": {
      "currency_code": "USD",
      "value": "100.00"
    }
  }]
}'

Payer approval

Call the payer approval flow by redirecting to the "approve" URL.

Authorize or capture order

After the payer approves, your server should call the following APIs:

Capture Order API if the intent passed was CAPTURE.
Authorize Order API if the intent passed was AUTHORIZE.

Authorize order request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
 -H "Content-Type: application/json" \
 -H "PayPal-Request-ID: 1337623214" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
 -d '{}'

Capture order request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
 -H "Content-Type: application/json" \
 -H "PayPal-Request-ID: 1337623214" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
 -d '{}'

The HTTP response codes HTTP 2xx or HTTP 200 are returned for a successful request.

The capture is successful if the purchase_units[0].payments.captures.status is COMPLETED. You can confirm with the payer that the payment has been captured.

{
        {
          "id": "9YF83379T2523751N",
          "status": "COMPLETED",
          "payment_source": {
            "paypal": {
              "email_address": "email@example.com",
              "account_id": "AJM9JTWQJCFTA",
              "name": {
                "given_name": "Firstname",
                "surname": "Lastname"
              },
              "address": {
                "country_code": "US"
              },
              "attributes": {
                "vault": {
                  "id": "nkq2y9g",
                  "customer": {
                    "id": "ROaPMoZUaV",
                    "merchant_customer_id": "customer@example.com"
                  },
                  "status": "VAULTED",
                  "links": [{
                      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/64n9c42",
                      "rel": "self",
                      "method": "GET"
                    },
                    {
                      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/64n9c42",
                      "rel": "delete",
                      "method": "DELETE"
                    },
                    {
                      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/9YF83379T2523751N",
                      "rel": "up",
                      "method": "GET"
                    }
                  ]
                }
              }
            }
          },
          "purchase_units": [{
            "reference_id": "default",
            "shipping": {
              "name": {
                "full_name": "Firstname Lastname"
              },
              "address": {
                "address_line_1": "1 Main St",
                "admin_area_2": "San Jose",
                "admin_area_1": "CA",
                "postal_code": "95131",
                "country_code": "US"
              }
            },
            "payments": {
              "captures": [{
                "id": "9LY87817BF120310A",
                "status": "COMPLETED",
                "amount": {
                  "currency_code": "USD",
                  "value": "100.00"
                },
                "final_capture": true,
                "seller_protection": {
                  "status": "ELIGIBLE",
                  "dispute_categories": [
                    "ITEM_NOT_RECEIVED",
                    "UNAUTHORIZED_TRANSACTION"
                  ]
                },
                "seller_receivable_breakdown": {
                  "gross_amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                  },
                  "paypal_fee": {
                    "currency_code": "USD",
                    "value": "3.98"
                  },
                  "net_amount": {
                    "currency_code": "USD",
                    "value": "96.02"
                  }
                },
                "links": [{
                    "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9LY87817BF120310A",
                    "rel": "self",
                    "method": "GET"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9LY87817BF120310A/refund",
                    "rel": "refund",
                    "method": "POST"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/9YF83379T2523751N",
                    "rel": "up",
                    "method": "GET"
                  }
                ],
                "create_time": "2022-08-12T18:16:42Z",
                "update_time": "2022-08-12T18:16:42Z"
              }]
            }
          }],
          "payer": {
            "name": {
              "given_name": "Firstname",
              "surname": "Lastname"
            },
            "email_address": "email@example.com",
            "payer_id": "AJM9JTWQJCFTA",
            "address": {
              "country_code": "US"
            }
          },
          "links": [{
            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/9YF83379T2523751N",
            "rel": "self",
            "method": "GET"
          }]
        }

In the response from the authorize or capture request, the Orders v2 API interacts with the Vault v3 API. The Vault v3 API allows a PayPal wallet to be saved. The response from the Orders v2 API contains the:

vault.id
vault.status
links for the payment token of a recently vaulted PayPal Wallet.

Check Orders API response

Saving a payment source doesn't require the payer to be present after the payment has been authorized or captured. To keep checkout times as short as possible for payers, the Orders API returns a response as soon as a payment is captured.

Payment may be authorized or captured and a successful response returned from the Orders API without the provided payment_source being saved. In this scenario, the response returns the attributes.vault.status as "APPROVED", instead of "VAULTED".

An example of the attributes object from this scenario is included in the following sample:

"attributes": {
        "vault": {
          "status": "APPROVED",
          "links": [
            {
              "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
              "rel": "up",
              "method": "GET"
            }
          ]
        }
      }

Webhooks for saving payment methods

You can configure and subscribe to the VAULT.PAYMENT-TOKEN.CREATED webhook, which is generated when saving payment methods with the Orders API.

You'll receive a vault_id when an APPROVED status is returned.

Event, Trigger, 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.

Next step

Follow Use payment method token with checkout for subsequent or recurring transactions.

Availability

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.
You must be approved to enable a reference transaction if you want to save PayPal as a payment source. Contact your account manager for details.

How it works

The payer saves their payment method.
For a first-time payer, PayPal creates a customer ID. Store this within your system for future use.
Pass a call into the Orders API. Include the payment method, customer ID, and an indication that the payment method should be saved.
If the order is processed and the payment method is saved, you receive a payment method token in the Orders API response.
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.

Server side

Create order and save payment

Platform

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-Request-ID: 1337623214" \
 -d '{
        "intent": "CAPTURE",
        "payment_source": {
        "paypal": {
          "attributes": {
            "customer": {
              "merchant_customer_id": "customer@example.com"
            },
            "vault": {
              "store_in_vault": "ON_SUCCESS",
              "usage_type": "PLATFORM"
            }
          },
          "experience_context": {
            "return_url": "https://example.com/returnUrl",
            "cancel_url": "https://example.com/cancelUrl"
        }
      }
    },
      "purchase_units": [{
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        },
        "payee": {
          "merchant_id": "MERCHANT-ID"
        }
      }]
    }'

Merchant

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-Auth-Assertion: AUTH-ASSERTION-TOKEN' \
-H 'PayPal-Partner-Attribution-ID: BN-CODE' \
-H "PayPal-Request-ID: 1337623214" \
-d '{
  "intent": "CAPTURE",
  "payment_source": {
    "paypal": {
      "attributes": {
        "customer": {
          "merchant_customer_id": "customer@example.com"
        },
        "vault": {
          "store_in_vault": "ON_SUCCESS",
          "usage_type": "MERCHANT"
        }
      },
      "experience_context": {
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl"
      }
    }
  },
  "purchase_units": [{
    "amount": {
      "currency_code": "USD",
      "value": "100.00"
    }
  }]
}'

Payer approval

Call the payer approval flow by redirecting to the "approve" URL.

Authorize or capture order

After the payer approves, your server should call the following APIs:

Capture Order API if the intent passed was CAPTURE.
Authorize Order API if the intent passed was AUTHORIZE.

Authorize order request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
 -H "Content-Type: application/json" \
 -H "PayPal-Request-ID: 1337623214" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
 -d '{}'

Capture order request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
 -H "Content-Type: application/json" \
 -H "PayPal-Request-ID: 1337623214" \
 -H "Authorization: Bearer ACCESS-TOKEN" \
 -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
 -d '{}'

The HTTP response codes HTTP 2xx or HTTP 200 are returned for a successful request.

The capture is successful if the purchase_units[0].payments.captures.status is COMPLETED. You can confirm with the payer that the payment has been captured.

{
        {
          "id": "9YF83379T2523751N",
          "status": "COMPLETED",
          "payment_source": {
            "paypal": {
              "email_address": "email@example.com",
              "account_id": "AJM9JTWQJCFTA",
              "name": {
                "given_name": "Firstname",
                "surname": "Lastname"
              },
              "address": {
                "country_code": "US"
              },
              "attributes": {
                "vault": {
                  "id": "nkq2y9g",
                  "customer": {
                    "id": "ROaPMoZUaV",
                    "merchant_customer_id": "customer@example.com"
                  },
                  "status": "VAULTED",
                  "links": [{
                      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/64n9c42",
                      "rel": "self",
                      "method": "GET"
                    },
                    {
                      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/64n9c42",
                      "rel": "delete",
                      "method": "DELETE"
                    },
                    {
                      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/9YF83379T2523751N",
                      "rel": "up",
                      "method": "GET"
                    }
                  ]
                }
              }
            }
          },
          "purchase_units": [{
            "reference_id": "default",
            "shipping": {
              "name": {
                "full_name": "Firstname Lastname"
              },
              "address": {
                "address_line_1": "1 Main St",
                "admin_area_2": "San Jose",
                "admin_area_1": "CA",
                "postal_code": "95131",
                "country_code": "US"
              }
            },
            "payments": {
              "captures": [{
                "id": "9LY87817BF120310A",
                "status": "COMPLETED",
                "amount": {
                  "currency_code": "USD",
                  "value": "100.00"
                },
                "final_capture": true,
                "seller_protection": {
                  "status": "ELIGIBLE",
                  "dispute_categories": [
                    "ITEM_NOT_RECEIVED",
                    "UNAUTHORIZED_TRANSACTION"
                  ]
                },
                "seller_receivable_breakdown": {
                  "gross_amount": {
                    "currency_code": "USD",
                    "value": "100.00"
                  },
                  "paypal_fee": {
                    "currency_code": "USD",
                    "value": "3.98"
                  },
                  "net_amount": {
                    "currency_code": "USD",
                    "value": "96.02"
                  }
                },
                "links": [{
                    "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9LY87817BF120310A",
                    "rel": "self",
                    "method": "GET"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9LY87817BF120310A/refund",
                    "rel": "refund",
                    "method": "POST"
                  },
                  {
                    "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/9YF83379T2523751N",
                    "rel": "up",
                    "method": "GET"
                  }
                ],
                "create_time": "2022-08-12T18:16:42Z",
                "update_time": "2022-08-12T18:16:42Z"
              }]
            }
          }],
          "payer": {
            "name": {
              "given_name": "Firstname",
              "surname": "Lastname"
            },
            "email_address": "email@example.com",
            "payer_id": "AJM9JTWQJCFTA",
            "address": {
              "country_code": "US"
            }
          },
          "links": [{
            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/9YF83379T2523751N",
            "rel": "self",
            "method": "GET"
          }]
        }

vault.id
vault.status
links for the payment token of a recently vaulted PayPal Wallet.

Check Orders API response

An example of the attributes object from this scenario is included in the following sample:

"attributes": {
        "vault": {
          "status": "APPROVED",
          "links": [
            {
              "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
              "rel": "up",
              "method": "GET"
            }
          ]
        }
      }

Webhooks for saving payment methods

You can configure and subscribe to the VAULT.PAYMENT-TOKEN.CREATED webhook, which is generated when saving payment methods with the Orders API.

You'll receive a vault_id when an APPROVED status is returned.

Event, Trigger, 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.

Next step

Follow Use payment method token with checkout for subsequent or recurring transactions.

Save PayPal with the Orders API

Availability

Supported countries

Know before you code

How it works

Server side

Create order and save payment

Platform

Merchant

Payer approval

Authorize or capture order

Authorize order request

Capture order request

Check Orders API response

Webhooks for saving payment methods

Next step

See also

On this page

On this page

On this page

Save PayPal with the Orders API

Availability

Supported countries

Know before you code

How it works

Server side

Create order and save payment

Platform

Merchant

Payer approval

Authorize or capture order

Authorize order request

Capture order request

Check Orders API response

Webhooks for saving payment methods

Next step

See also

On this page

On this page

Save PayPal with the Orders API

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 PayPal with the Orders API

On this page

On this page