Vault with the Orders API

Save your buyer's payment method during a transaction with the Orders API

Version notice: This integration uses Vault v2. Vault v3 is now available in the United States. Payment tokens created with Vault v2 are fully compatible with Vault v3. You can upgrade to v3 at any time.

Important: Vaulting payment methods is a limited-release solution available to select merchants and partners as a pilot. Contact your sales or account manager to inquire about the pilot. You may need to configure your developer account to use vaulting in both the sandbox and production environments separately. To use vaulted card information in a transaction, you must follow the onboarding and vetting process for advanced credit and debit card processing. To use a vaulted PayPal wallet in a transaction, you must be approved for PayPal Billing Agreements.

Warning: To continue providing a Pay Later option at checkout, it is essential that you integrate Billing With Purchase. This solution offers the same functionalities as Billing Agreement and is compatible with your existing payment options.

Vaulting securely saves your buyers' payment method and streamlines their checkout experience. Use the Orders API to create a transaction and then save the payment method used.

Use a direct integration with the Orders API if you are PCI compliant (when capturing and passing card information), have opted not to integrate with a PayPal client-side JavaScript SDK, and want to both make a purchase and vault the instrument used. To vault a payment instrument outside of a purchase, use the Payment Method Tokens API.

Know before you code

Vaulting is currently supported for two payment method types: cards and PayPal. Other payment methods are not supported yet.
This procedure modifies an existing integration with the Orders API.
To vault payment methods, you must uniquely identify your customers. For example, buyers create an account and log in to your site.
To use vaulting, contact your account manager who can help configure your account.
You must be approved for and have your account configured to create and use billing agreements if you want to save PayPal as a payment source. Contact your account manager for details.
You must be approved for and have your account configured for advanced credit and debit card payments if you want to save a card. See the Setup advanced credit and debit card payments guide for details.
Passing card data to the Orders API requires SAQ D PCI Compliance.

How it works

When your buyer requests that you save their payment method, PayPal creates a customer record. PayPal then encrypts the payment method information and stores it in a digital vault for that customer. This vault is accessible by you only. The steps are as follows:

Your buyer initiates a purchase and chooses to save their payment method.
You identify the buyer by a unique customer ID in your system.
You pass that payment method into the Orders API along with a customer ID and an indication that the method should be vaulted.
If the order is successfully processed and the instrument vaulted, you will receive a payment method token in the Orders API response.
When you want to create another payment, pass the payment method token into the Orders API. This can make a buyer's checkout shorter because they don't have to type in the underlying payment method details.

Vault the payment method

The Orders API supports vaulting the following payment methods:

PayPal
Cards for advanced credit and debit card payments

To vault any payment method you need a way to uniquely identify your customer, such as credentials they use to log in to your site. You must have a unique ID for each customer to vault their payment method.

To request that a payment method be vaulted, modify the attributes object within the payment_source parameter in any of the following calls:

POST on /v2/checkout/orders/{id}/authorize
POST on /v2/checkout/orders/{id}/capture
POST on /v2/checkout/orders (to use one call to do both the create and authorize/capture)

Vault PayPal

To vault a PayPal account, the buyer needs to be present when the transaction takes place to authenticate against the PayPal account they want to save.

Modify your integration

Modify your integration with the Orders API endpoint that you use to initiate a transaction:

Include attributes in the payment_source.
Set the customer.id to the unique ID you used to identify this specific customer.
Set the attributes.vault parameters as appropriate for your use case.

Sample request

"payment_source": {
        "paypal": {
            "attributes": {
                "customer": {
                    "id": "wxj1234"
                },
                "vault": {
                    "confirm_payment_token": "ON_ORDER_COMPLETION",
                    "usage_type": "MERCHANT",
                    "customer_type": "CONSUMER"
                }
            }
        }
 },

Result

The call to the Orders API to create or initiate a charge using a PayPal account as the payment source results in a PAYER_ACTION_REQUIRED contingency. Once the buyer has identified their PayPal account, authenticated, and been redirected, you call a POST on either /v2/checkout/orders/{id}/authorize, or /v2/checkout/orders/{id}/capture, depending on your integration. A successful response from that call can now include the following:

A payment method token, which is returned in the id parameter of the attributes.vault object.
A HATEOAS link for a GET on the payment method token.
The status of the payment method token:
- A value of CREATED indicates that the buyer has approved saving their PayPal account and it has been successfully vaulted. This token can be used in subsequent transactions to charge the buyer's PayPal account, rather than requiring them to identify and log in for every purchase. With this status there will be a payment-method-token HATEOAS link to perform a GET on the payment token using the Payment Method Tokens API.
- A value of APPROVED indicates that the buyer has approved saving their PayPal account, but the account hasn't yet been added to the vault. In this case there is no id and the payment method token hasn't been created yet. There will be a confirm-payment-token HATEOAS link to perform a POST against an approval-token. This call will attempt to store the instrument to the vault and, if successful, will return a long-lived payment method token in the response. The approval token has a lifespan of only three hours.

Note: The payment methods isn't vaulted if the primary action, the payment authorization, or capture fails.

Sample response from successful vaulting

"payment_source": {
    "paypal": {
      "attributes": {
        "vault": {
          "id": "m6yd4yw",
          "status": "CREATED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/m6yd4yw",
      "rel": "payment-token",
      "method": "GET"
    }
  ]

Sample response when vaulting is approved but there is a vaulting failure that can be retried

"payment_source": {
    "paypal": {
      "attributes": {
        "vault": {
          "status": "APPROVED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/approval-tokens/7J625341K0052023Y/confirm-payment-token",
      "rel": "confirm-payment-token",
      "method": "POST"
    }
  ]

Vault cards

To vault cards, you'll use the server-side Orders API.

Modify your existing Orders API integration

Modify your integration with the Orders API endpoint that you use to initiate a transaction to add vaulting of the card used in the purchase. Make the following changes:

Include attributes in the card object of your payment_source.
Set the customer.id to the unique ID you used to identify this specific customer.
Set the attributes.vault parameter as appropriate for your use case.

Sample request

"payment_source": {
        "card": {
            "number": "4111111111111111",
            "expiry": "2024-12",
            "name": "John Doe",
            "billing_address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "Building 17",
                "admin_area_1": "CA",
                "admin_area_2": "San Jose",
                "postal_code": "95131",
                "country_code": "US"
            },
            "attributes": {
                "customer": {
                    "id": "wxj1234"
                },
                "vault": {
                    "confirm_payment_token": "ON_ORDER_COMPLETION"
                }
            }
        }
    }

Result

A successful response includes the following:

The payment method token is returned in the id parameter of the attributes.vault object.
A HATEOAS link for a GET on the payment method token.
The status of the payment token:
- A value of CREATED indicates the instrument has been successfully vaulted. This token can be used in subsequent transactions in place of the buyer logging in to their PayPal account. There will also be a payment-method-token HATEOAS link to perform a GET on the payment token using the Payment Method Tokens API.
- A value of APPROVED indicates that the authorize or capture was successful but that it hasn't been added to the vault yet. In this case, there is no id returned. There will be a confirm-payment-token HATEOAS link to perform a POST against an approval-token. This call will attempt to store the instrument to the vault and, if successful, will return a long-lived payment token in the response. The approval token has a lifespan of only 3 hours.
Nothing is vaulted, and no additional data is added to the response if the primary action, the authorize or capture, fails.

Sample response from successful vaulting

"payment_source": {
    "card": {
      "last_digits": "1111",
      "brand": "VISA",
      "attributes": {
        "vault": {
          "id": "7dyps8w",
          "status": "CREATED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/7dyps8w",
      "rel": "payment-token",
      "method": "GET"
    }
  ]

Sample response for purchase success but vaulting failure

"id": "5O190127TN364715T",
  "status": "COMPLETED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "brand": "VISA",
      "attributes": {
        "vault": {
          "status": "APPROVED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/approval-tokens/7J625341K0052023Y/confirm-payment-token",
      "rel": "confirm-payment-token",
      "method": "POST"
    }
  ]

Next step

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

To learn more about webhooks, see the webhooks documentation.

Save your buyer's payment method during a transaction with the Orders API

Vaulting securely saves your buyers' payment method and streamlines their checkout experience. Use the Orders API to create a transaction and then save the payment method used.

Know before you code

Vaulting is currently supported for two payment method types: cards and PayPal. Other payment methods are not supported yet.
This procedure modifies an existing integration with the Orders API.
To vault payment methods, you must uniquely identify your customers. For example, buyers create an account and log in to your site.
To use vaulting, contact your account manager who can help configure your account.
You must be approved for and have your account configured to create and use billing agreements if you want to save PayPal as a payment source. Contact your account manager for details.
You must be approved for and have your account configured for advanced credit and debit card payments if you want to save a card. See the Setup advanced credit and debit card payments guide for details.
Passing card data to the Orders API requires SAQ D PCI Compliance.

How it works

Your buyer initiates a purchase and chooses to save their payment method.
You identify the buyer by a unique customer ID in your system.
You pass that payment method into the Orders API along with a customer ID and an indication that the method should be vaulted.
If the order is successfully processed and the instrument vaulted, you will receive a payment method token in the Orders API response.
When you want to create another payment, pass the payment method token into the Orders API. This can make a buyer's checkout shorter because they don't have to type in the underlying payment method details.

Vault the payment method

The Orders API supports vaulting the following payment methods:

PayPal
Cards for advanced credit and debit card payments

To request that a payment method be vaulted, modify the attributes object within the payment_source parameter in any of the following calls:

POST on /v2/checkout/orders/{id}/authorize
POST on /v2/checkout/orders/{id}/capture
POST on /v2/checkout/orders (to use one call to do both the create and authorize/capture)

Vault PayPal

To vault a PayPal account, the buyer needs to be present when the transaction takes place to authenticate against the PayPal account they want to save.

Modify your integration

Modify your integration with the Orders API endpoint that you use to initiate a transaction:

Include attributes in the payment_source.
Set the customer.id to the unique ID you used to identify this specific customer.
Set the attributes.vault parameters as appropriate for your use case.

Sample request

"payment_source": {
        "paypal": {
            "attributes": {
                "customer": {
                    "id": "wxj1234"
                },
                "vault": {
                    "confirm_payment_token": "ON_ORDER_COMPLETION",
                    "usage_type": "MERCHANT",
                    "customer_type": "CONSUMER"
                }
            }
        }
 },

Result

A payment method token, which is returned in the id parameter of the attributes.vault object.
A HATEOAS link for a GET on the payment method token.
The status of the payment method token:
- A value of CREATED indicates that the buyer has approved saving their PayPal account and it has been successfully vaulted. This token can be used in subsequent transactions to charge the buyer's PayPal account, rather than requiring them to identify and log in for every purchase. With this status there will be a payment-method-token HATEOAS link to perform a GET on the payment token using the Payment Method Tokens API.
- A value of APPROVED indicates that the buyer has approved saving their PayPal account, but the account hasn't yet been added to the vault. In this case there is no id and the payment method token hasn't been created yet. There will be a confirm-payment-token HATEOAS link to perform a POST against an approval-token. This call will attempt to store the instrument to the vault and, if successful, will return a long-lived payment method token in the response. The approval token has a lifespan of only three hours.

Note: The payment methods isn't vaulted if the primary action, the payment authorization, or capture fails.

Sample response from successful vaulting

"payment_source": {
    "paypal": {
      "attributes": {
        "vault": {
          "id": "m6yd4yw",
          "status": "CREATED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/m6yd4yw",
      "rel": "payment-token",
      "method": "GET"
    }
  ]

Sample response when vaulting is approved but there is a vaulting failure that can be retried

"payment_source": {
    "paypal": {
      "attributes": {
        "vault": {
          "status": "APPROVED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/approval-tokens/7J625341K0052023Y/confirm-payment-token",
      "rel": "confirm-payment-token",
      "method": "POST"
    }
  ]

Vault cards

To vault cards, you'll use the server-side Orders API.

Modify your existing Orders API integration

Modify your integration with the Orders API endpoint that you use to initiate a transaction to add vaulting of the card used in the purchase. Make the following changes:

Include attributes in the card object of your payment_source.
Set the customer.id to the unique ID you used to identify this specific customer.
Set the attributes.vault parameter as appropriate for your use case.

Sample request

"payment_source": {
        "card": {
            "number": "4111111111111111",
            "expiry": "2024-12",
            "name": "John Doe",
            "billing_address": {
                "address_line_1": "2211 N First Street",
                "address_line_2": "Building 17",
                "admin_area_1": "CA",
                "admin_area_2": "San Jose",
                "postal_code": "95131",
                "country_code": "US"
            },
            "attributes": {
                "customer": {
                    "id": "wxj1234"
                },
                "vault": {
                    "confirm_payment_token": "ON_ORDER_COMPLETION"
                }
            }
        }
    }

Result

A successful response includes the following:

The payment method token is returned in the id parameter of the attributes.vault object.
A HATEOAS link for a GET on the payment method token.
The status of the payment token:
- A value of CREATED indicates the instrument has been successfully vaulted. This token can be used in subsequent transactions in place of the buyer logging in to their PayPal account. There will also be a payment-method-token HATEOAS link to perform a GET on the payment token using the Payment Method Tokens API.
- A value of APPROVED indicates that the authorize or capture was successful but that it hasn't been added to the vault yet. In this case, there is no id returned. There will be a confirm-payment-token HATEOAS link to perform a POST against an approval-token. This call will attempt to store the instrument to the vault and, if successful, will return a long-lived payment token in the response. The approval token has a lifespan of only 3 hours.
Nothing is vaulted, and no additional data is added to the response if the primary action, the authorize or capture, fails.

Sample response from successful vaulting

"payment_source": {
    "card": {
      "last_digits": "1111",
      "brand": "VISA",
      "attributes": {
        "vault": {
          "id": "7dyps8w",
          "status": "CREATED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/payment-tokens/7dyps8w",
      "rel": "payment-token",
      "method": "GET"
    }
  ]

Sample response for purchase success but vaulting failure

"id": "5O190127TN364715T",
  "status": "COMPLETED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "brand": "VISA",
      "attributes": {
        "vault": {
          "status": "APPROVED"
        }
      }
    }
  },
...

"links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/vault/approval-tokens/7J625341K0052023Y/confirm-payment-token",
      "rel": "confirm-payment-token",
      "method": "POST"
    }
  ]

Next step

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

To learn more about webhooks, see the webhooks documentation.

Vault with the Orders API

Know before you code

How it works

Vault the payment method

Vault PayPal

Modify your integration

Sample request

Result

Sample response from successful vaulting

Sample response when vaulting is approved but there is a vaulting failure that can be retried

Vault cards

Modify your existing Orders API integration

Sample request

Result

Sample response from successful vaulting

Sample response for purchase success but vaulting failure

Next step

On this page

On this page

On this page

Vault with the Orders API

Know before you code

How it works

Vault the payment method

Vault PayPal

Modify your integration

Sample request

Result

Sample response from successful vaulting

Sample response when vaulting is approved but there is a vaulting failure that can be retried

Vault cards

Modify your existing Orders API integration

Sample request

Result

Sample response from successful vaulting

Sample response for purchase success but vaulting failure

Next step

On this page

On this page

Vault 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

Vault with the Orders API

On this page

On this page