# Save PayPal with the Orders API (/api/orders-v2/save-with-purchase/paypal) Use the Orders API to save PayPal payment methods for faster checkout. Enable customers to complete future transactions without re-entering payment details. 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](/api/orders/v2) to create a transaction and save the payer's PayPal Wallet. 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 make a purchase and save the instrument used. To save a payment method outside of a purchase, use the [Vault Payment Method API](/api/payment-tokens/v3). > **Warning:** **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](/platforms/checkout/standard/best-practices/). ## Availability [#availability] ### See supported countries [#see-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 [#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 [#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. ## Check eligibility [#check-eligibility] 1. Go to [paypal.com](https://www.paypal.com/) and sign in with your business account. 2. Go to **Account Settings** > **Payment Preferences** > **Save PayPal and Venmo payment methods**. 3. In the Save PayPal and Venmo payment methods section, select **Get Started**. 4. When you submit profile details, PayPal reviews your eligibility to save PayPal Wallets and Venmo accounts. 5. After PayPal reviews your eligibility, you'll see a status of **Success**, **Need more information**, or **Denied**. ## Set up your account to save payment methods [#set-up-your-account-to-save-payment-methods] Enable the vaulting feature in the Developer Dashboard for both your sandbox and production apps before you integrate. ### Sandbox [#sandbox] Set up your sandbox business account to save payment methods: 1. Log in to the Developer Dashboard. 2. Under **REST API apps**, select your app name. 3. Under **Sandbox App Settings** > **App Feature Options**, check **Accept payments**. 4. Expand **Advanced options**. Confirm that **Vault** is selected. ### Production [#production] Set up your live business account to save payment methods: 1. Log in to the [PayPal Developer Dashboard](https://developer.paypal.com/home/). 2. In the navigation menu, use the **Sandbox | Live** toggle to select **Live**. 3. Access **Apps & Credentials**. 4. Select the production REST API app name. 5. To enable vaulting for your account: 1. Go to **Features** > **Payment capabilities**. 2. In the **Payment capabilities** menu, select the **Save payment methods** toggle to enable vaulting. 6. To add the ability to save PayPal and Venmo payment methods: 1. Go to **Features** > **Payment methods**. 2. In the **Payment methods** menu, select the **PayPal and Venmo** toggle so you can save PayPal and Venmo payment options. > **Warning:** 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](/ratepay/fraudnet) > > and > > [Magnes](/limited-release/magnes) > > libraries to collect and pass RDA data during payment processing. ## Server side [#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. ### Request to create an order and save PayPal [#request-to-create-an-order-and-save-paypal] > **Warning:** 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](/ratepay/fraudnet) > > and > > [Magnes](/limited-release/magnes) > > libraries to collect and pass RDA data during payment processing. ```bash lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS-TOKEN" \ -d '{ "intent": "CAPTURE", "payment_source": { "paypal": { "attributes": { "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" } } ] }' ``` ### Response [#response] 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. ```json lineNumbers { "id": "46299262185816041", "status": "PAYER_ACTION_REQUIRED", "payment_source": { "paypal": {} }, "links": [{ "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/46299262185816041", "rel": "self", "method": "GET", }, { "href": "https://www.sandbox.paypal.com/checkoutnow?token=46299262185816041", "rel": "approve", "method": "GET", } ] } ``` ## Payer approval [#payer-approval] 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. ## Authorize or capture order [#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`. ### Request [#request] ### Authorize [#authorize] ```bash lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \ -H "Content-Type: application/json"\ -H "Authorization: Bearer ACCESS-TOKEN"\ -d '{}' ``` ### Capture [#capture] ```bash lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS-TOKEN" \ -d '{}' ``` ### Response [#response-1] 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. ```json lineNumbers { "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" }, "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 [#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 ```json lineNumbers "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 [#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 | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `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](/api/payment-tokens/v3/payment-tokens-delete). | PayPal | For more information on webhooks, see [webhooks](/api/rest/webhooks/). ## Next step [#next-step] Follow [Use payment method token with checkout](/api/payment-tokens/save-without-purchase/paypal) for subsequent or recurring transactions. ## See also [#see-also] [Payment Method Token API errors](/api/payment-tokens/v3/errors/)