Vault with the Orders API

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

DocsCurrentLast updated: June 19th 2023, @ 5:00:00 pm


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:

  1. Your buyer initiates a purchase and chooses to save their payment method.
  2. You identify the buyer by a unique customer ID in your system.
  3. You pass that payment method into the Orders API along with a customer ID and an indication that the method should be vaulted.
  4. If the order is successfully processed and the instrument vaulted, you will receive a payment method token in the Orders API response.
  5. 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)
  1. Vault PayPal
  2. Vault cards
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"
    }
  ]

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.

ReferencePayPal.comPrivacyCookiesSupportLegalContact