# Vault with the Orders API (/limited-release/vault-payment-methods/orders-api) Save your buyer's payment method during a transaction with the Orders API > **Note:** **Version notice:** This integration uses Vault v2. [Vault v3](/platforms/checkout/save-payment-methods/during-purchase/orders-api/paypal/) 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. > **Note:** **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. > **Note:** **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](/api/orders/v2) 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](/limited-release/vault-payment-methods/vault-api/). ## Know before you code [#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](/api/orders/v2). * 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](/platforms/checkout/advanced/integrate) for details. * Passing card data to the Orders API requires SAQ D PCI Compliance. ## How it works [#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 [#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 [#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] Modify your integration with the Orders API endpoint that you use to initiate a transaction: * Include [`attributes`](/api/orders/v2#definition-paypal_wallet_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 [#sample-request] ```json lineNumbers "payment_source": { "paypal": { "attributes": { "customer": { "id": "wxj1234" }, "vault": { "confirm_payment_token": "ON_ORDER_COMPLETION", "usage_type": "MERCHANT", "customer_type": "CONSUMER" } } } }, ``` #### Result [#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](/api/limited-release/payment-tokens/v2/). * 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`](https://ppaas/api/3719176155269077?tab=apiReference\&operation_id=post-_v2_vault_approval_tokens_id_confirm_payment_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:** **Note:** The payment methods isn't vaulted if the primary action, the payment authorization, or capture fails. #### Sample response from successful vaulting [#sample-response-from-successful-vaulting] ```json lineNumbers "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 [#sample-response-when-vaulting-is-approved-but-there-is-a-vaulting-failure-that-can-be-retried] ```json lineNumbers "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 [#vault-cards] To vault cards, you'll use the server-side Orders API. ### Modify your existing Orders API integration [#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`](/api/orders/v2#definition-card_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 [#sample-request-1] ```json lineNumbers "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 [#result-1] 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](/api/limited-release/payment-tokens/v2/). * 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`](https://ppaas/api/3719176155269077?tab=apiReference\&operation_id=post-_v2_vault_approval_tokens_id_confirm_payment_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 [#sample-response-from-successful-vaulting-1] ```json lineNumbers "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 [#sample-response-for-purchase-success-but-vaulting-failure] ```json lineNumbers "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 [#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](/api/rest/webhooks/rest/).