---
title: Save Venmo with the JavaScript SDK
layout: limited-release-docs
date: 2022-06-08T21:16:47Z
---
Vaulting securely saves the payer's payment method and streamlines their checkout experience.
<!--## Technical flow
-->
## Know before you code
You'll need a PayPal Developer account for this integration. You can sign up for a PayPal Developer Account [here](https://www.paypal.com/signin/client?flow=provisionUser&country.x=US&locale.x=en_US)
> **Note**: The API URLs shown in the following examples point to production. Venmo is not fully supported in the sandbox environment. For more information, refer to the [Venmo testing guidlines](/docs/checkout/pay-with-venmo/integrate/#link-testandgolive).
## 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 wallet for that customer which is accessible only by you.
1. The payer chooses to save their payment method.
1. For a first-time payer, PayPal generates a customer ID. Store this within your system for future use.
1. When the payer returns to your website and is ready to check out, you pass their PayPal generated customer ID to the PayPal JavaScript SDK to indicate you want to save or reuse a saved payment method.
1. The PayPal JavaScript SDK populates the checkout page with each saved payment method. Each payment method displays as one-click payment buttons alongside other ways to pay.
The checkout process is now shorter because it uses the saved payment information.
## 1. Generate user id token for payer
The OAuth 2.0 API to retrieve an [<code>access_token</code>](/api/rest/authentication/#link-curl) has an additional parameter, <code>response_type</code> that can be set to <code>id_token</code> to include the <code>id_token</code> in the response along with the <code>access_token</code>.
<ContentTabs>
<ContentTab label="First-time User">
For a first-time payer, generate a user ID token with the OAuth 2.0 API call as shown below.
Copy the following code and modify it:
### Sample server-side user id token request
<CodeBlockWrapper>
<CodeBlock
className="language-bash"
children={`
curl -s -X POST "https://api-m.paypal.com/v1/oauth2/token" \\\n -u CLIENT_ID:CLIENT_SECRET \\\n -H "Content-Type: application/x-www-form-urlencoded" \\\n -d "grant_type=client_credentials" \\\n -d "response_type=id_token"
`}
/>
</CodeBlockWrapper>
### Modify the code
1. Copy the sample request code.
1. Change <code>CLIENT_ID</code> to your client ID.
1. Change <code>CLIENT_SECRET</code> to your client secret.
</ContentTab>
<ContentTab label="Returning User">
For a returning user, use the saved PayPal-generated customer ID in the POST body parameter, <code>target_customer_id</code> when requesting for the user ID token as shown below. The <code>customer ID</code> is a unique ID for a customer that was generated by PayPal when saving the <code>payment_source</code> into the vault. This customer ID is available when capturing the order or retrieving the saved payment information as shown in step 5.
> **Note:** PayPal requires that you use the customer identifier as generated by PayPal and not the identifier that you use to identify the customer in your system.
### Sample server-side user id token request with a PayPal generated customer ID
<CodeBlockWrapper>
<CodeBlock
className="language-bash"
children={`
curl -s -X POST "https://api-m.paypal.com/v1/oauth2/token" \\\n -u CLIENT_ID:CLIENT_SECRET \\\n -H "Content-Type: application/x-www-form-urlencoded" \\\n -d "grant_type=client_credentials" \\\n -d "response_type=id_token" \\\n -d "target_customer_id=PayPal-generated customer id"
`}
/>
</CodeBlockWrapper>
### Modify the code
1. Copy the sample request code.
1. Change <code>CLIENT_ID</code> to your client ID.
1. Change <code>CLIENT_SECRET</code> to your client secret.
1. Replace the <code>PayPal generated customer id</code> with the actual one that was stored in your system.
</ContentTab>
</ContentTabs>
### Sample response
<CodeBlockWrapper>
<CodeBlock className="language-json" children={`
{
"access_token" : "A21AALfqL90lNr8kExf9CI8cQIP19XkpBfdyFf3nPdTc0XbXCNXdrrK92QaywEZ2jqNIyumP_fezAwMOibDaOWqGONVfyob5g",
"app_id" : "APP-80W284485P519543T",
"expires_in" : 32400,
"id_token" : "eyJraWQiOiJjMmVjMmZiYjIzMGU0ZDkzOTNhMGFmZjEzZTY4MjFjMSIsInR5cCI6IkpXVCIsImFsZyI6IkVTMjU2In0.eyJpc3MiOiJodHRwczovL2FwaS5zYW5kYm94LnBheXBhbC5jb20iLCJzdWIiOiJQQ0haQ1RMMjVSNllXIiwiYWNyIjpbImNsaWVudCJdLCJzY29wZSI6WyJCcmFpbnRyZWU6VmF1bHQiXSwib3B0aW9ucyI6eyJjdXN0b21lcl9pZCI6IjIxMzM3NTk5MiJ9LCJheiI6ImdjcC5zbGMiLCJleHRlcm5hbF9pZCI6WyJQYXlQYWw6UENIWkNUTDI1UjZZVyIsIkJyYWludHJlZTo2ZDNtY3pqN2h3cHE4Y2cyIl0sImV4cCI6MTY2NDIzODEwMiwiaWF0IjoxNjY0MjM3MjAyLCJqdGkiOiJVMkFBSkVBN21DaWtTSGlfd3c2OVM5ZW92Vmo0UXZGanVNZzZYLUlZN1VqNDh4Z3NIaEhEVUZoelRFSG1vRGdvSXczcnFieTFFSEpubDFmb19SNFF3SVhPTlVPbHQ0dmZVQ0RxdklrRUdmWFdqeGNnYUNfTWVnam1KNk1IVTdVUSJ9.iMDYOU8RA6lv0U06LHcOSmpdEX6fVP4Y3-NLExZ28hUpBNDtCQ9NXxmYhjjAiYAbdtpVaYQjpig1NawbuAHNug",
"nonce" : "2022-09-27T00:06:42ZtVVASdHDZEsuDY56mMQp6wlR5rOknNY1LqrC1oOVVmI",
"scope" : "https://uri.paypal.com/services/invoicing https://uri.paypal.com/services/vault/payment-tokens/read https://uri.paypal.com/services/disputes/read-buyer https://uri.paypal.com/services/payments/realtimepayment https://uri.paypal.com/services/disputes/update-seller https://uri.paypal.com/services/paypalhere openid https://uri.paypal.com/services/payments/payment/authcapture https://uri.paypal.com/services/disputes/read-seller Braintree:Vault https://uri.paypal.com/services/payments/refund https://uri.paypal.com/services/identity/activities https://api.paypal.com/v1/vault/credit-card https://api.paypal.com/v1/payments/.* https://uri.paypal.com/services/reporting/search/read https://uri.paypal.com/payments/payouts https://uri.paypal.com/services/vault/payment-tokens/readwrite https://api.paypal.com/v1/vault/credit-card/.* https://uri.paypal.com/services/shipping/trackers/readwrite https://uri.paypal.com/services/subscriptions https://uri.paypal.com/services/applications/webhooks https://api.paypal.com/v1/payments/refund https://api.paypal.com/v1/payments/sale/.*/refund",
"token_type" : "Bearer"
}
`}/>
</CodeBlockWrapper>
A successful request results in a <code>access_token</code>, <code>id_token</code>, the number of seconds the <code>access_token</code> token is valid along with other fields. The <code>id_token</code> expiry is much shorter in minutes range as it is meant to be used during a payer session.
You can generate new token pairs if the current tokens expire.
>**Tip**: Because each payer session is unique, set up your server to generate new token pairs each time you render the checkout page.
The <code>id_token</code> shown in the response above uniquely identifies each payer. This is required to initialize the Javascript SDK script tag as shown in Step 2.
## 2. Add Venmo button
* Render the Venmo button on your website by adding the PayPal JavaScript SDK code to your product and checkout pages.
* Determine where the SDK should render the Venmo button. You can control the presentment of the button using configuration attributes.
* Pass the <code>id_token</code> from your server into the PayPal JavaScript SDK using the <code>data-user-id-token</code>.
### Client side
<CodeBlockWrapper>
<CodeBlock className="language-html" children={`
<!-- Set up a container element for the button -->
<div id="venmo-button-container"></div>
<!-- Include the PayPal JavaScript SDK. Replace 'YOUR_CLIENT_ID' with your client ID.-->
<!-- Note that 'enable-funding=venmo' is added as a query parameter -->
<!-- Replace 'YOUR_ID_TOKEN' with the id_token from your server in step 1. -->
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&enable-funding=venmo" data-user-id-token="YOUR_ID_TOKEN"></script>
<script>
// Render the Venmo button into #paypal-button-container
paypal.Buttons().render('#venmo-button-container')
</script>
`}/>
</CodeBlockWrapper>
## 3. Create order
### Client side
Include the client-side callbacks to manage interactions with APIs, payer approval flows, and any events that lead to cancellation or error during payer approval.
<CodeBlockWrapper>
<CodeBlock className="language-javascript" children={`
<script>
paypal.Buttons({
// Call your server to set up the transaction
createOrder: function(data, actions) {
return fetch('/yourserver.com/createOrder', {
method: 'post'
}).then(function(res) {
return res.json();
}).then(function(orderData) {
return orderData.id;
});
},
// Authorize or capture the transaction after payer approves
onApprove: (data, actions) => {
return actions.order.capture().then(function(orderData) {
//Authorize or Capture API
return fetch('/yourserver.com/order/' + data.orderID + '/capture/', {
method: 'post'
})
},
onCancel(data, actions) {
console.log(\`Order Canceled - ID: \${data.orderID}\`);
},
onError(err) {
console.error(err);
}
}).render('#paypal-button-container');
</script>
`}/>
</CodeBlockWrapper>
### Server side
Set up your server to invoke the Create Order API. The button pressed on the client side determines the <code>payment_source</code> sent in the following sample. To save Venmo as a payment method, pass the appropriate attributes via <code>payment_source.venmo.attributes</code> with the value <code>ON_SUCCESS</code>.
#### Request
Create an order with Venmo as a payment source:
<CodeBlockWrapper>
<CodeBlock className="language-bash" children={`
curl -v -X POST https://api-m.paypal.com/v2/checkout/orders \\\n -H "Content-Type: application/json" \\\n -H "Authorization: Bearer Access-Token" \\\n -d '{
"intent": "CAPTURE",
"purchase_units": [{
"amount": {
"currency_code": "USD",
"value": "100.00"
}
}],
"payment_source": {
"venmo": {
"email_address": "customer@example.com",
"experience_context": {
"shipping_preference": "SET_PROVIDED_ADDRESS",
"brand_name": "EXAMPLE INC"
},
"attributes": {
"vault": {
"store_in_vault": "ON_SUCCESS",
"usage_type": "MERCHANT"
}
}
}
}
}
`}/>
</CodeBlockWrapper>
#### Response
Check the status of the response. In the cases of a <code>payment_source</code> that needs payer approval, return the <code>id</code> to your client to invoke the payer approval flow.
<CodeBlockWrapper>
<CodeBlock className="language-json" children={`
{
"id": "5O190127TN364715T",
"status": "PAYER_ACTION_REQUIRED",
"payment_source": {
"venmo": {
"email_address": "customer@example.com"
}
},
"links": [{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}]
}
`}/>
</CodeBlockWrapper>
## 4. Payer approval
Once the control passes to the client SDK, it invokes the payer approval flow. In the case of Venmo, this could be a switch to the Venmo app or a QR code if the payer doesn't have the app installed or is viewing it on a desktop.
## 5. Authorize or capture order
Once the payer approves, the <code>onApprove</code> function is called in the JS SDK. At this point, your server should:
* Call the Capture Order API if the <code>intent</code> passed was <code>CAPTURE</code>
* Call the Authorize Order API if the <code>intent</code> passed was <code>AUTHORIZE</code> as part of your Create Order call.
### Authorize order request call
<CodeBlockWrapper>
<CodeBlock className="language-bash" children={`
curl -v -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \\\n -H "Content-Type: application/json" \\\n -H "Authorization: Bearer Access-Token" \\\n -d '{}'
`}/>
</CodeBlockWrapper>
### Capture order request call
<CodeBlockWrapper>
<CodeBlock className="language-bash" children={`
curl -v -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \\\n -H "Content-Type: application/json" \\\n -H "Authorization: Bearer Access-Token" \\\n -d '{}'
`}/>
</CodeBlockWrapper>
### Capture order response
A successful response is <code>HTTP 2xx</code> or <code>HTTP 200</code> returned for an idempotent request.
Confirm that the capture is successful by asserting that <code>purchase_units[0].payments.captures.status</code> is <code>COMPLETED</code>.You can now confirm to the payer that the payment has been captured.
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:
* <code>vault_id</code>
* <code>customer.id</code>
* <code>vault_status</code>
* <code>links</code> for the payment token of a recently vaulted PayPal Wallet.
On a successful response, the <code>payment_source.venmo.attribute.vault.status</code> will be set to <code>VAULTED</code> along with the vault ID at <code>payment_source.venmo.attribute.vault.id</code>.
Capture order response:
<CodeBlockWrapper>
<CodeBlock className="language-json" children={`
{
"id": "5O190127TN364715T",
"status": "COMPLETED",
"payment_source": {
"venmo": {
"user_name": "nickname",
"name": {
"given_name": "John",
"surname": "Doe"
},
"email_address": "customer@example.com",
"phone_number": {
"national_number": "2025212022"
},
"account_id": "QYR5Z8XDVJNXQ",
"address": {
"address_line_1": "123 Townsend St",
"address_line_2": "Floor 6",
"admin_area_2": "San Francisco",
"admin_area_1": "CA",
"postal_code": "94107",
"country_code": "US"
},
"attribute": {
"vault": {
"id": "ckfmsf",
"customer": {
"id": "4029352050"
},
"status": "VAULTED",
"links": [{
"href": "https://api-m.paypal.com/v3/vault/payment-tokens/ckfmsf",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v3/vault/payment-tokens/ckfmsf",
"rel": "delete",
"method": "DELETE"
},
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "up",
"method": "GET"
}
]
}
}
}
},
"purchase_units": [{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"payments": {
"captures": [{
"id": "3C679366HH908993F",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"final_capture": true,
"disbursement_mode": "INSTANT",
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "100.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "3.00"
},
"net_amount": {
"currency_code": "USD",
"value": "97.00"
}
},
"create_time": "2022-01-01T21:20:49Z",
"update_time": "2022-01-01T21:20:49Z",
"links": [{
"href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "up",
"method": "GET"
}
]
}]
}
}]
}
`}/>
</CodeBlockWrapper>
Saving a payment source does not require the payer to be present after the payment has been successfuly authorized or captured. Therefore, in order to keep checkout times as short as possible for payers, the Orders API is optimized to return a response as soon as a payment is captured.
This means that the payment may be authorized or captured and a successful response is retured from the Orders API without the provided <code>payment_source</code> being vaulted. The Orders response after authorization or capture will instead return <code>attributes.vault.status</code> as <code>"APPROVED"</code>, instead of <code>"VAULTED"</code>.
An example of the <code>attributes</code> object from this scenario is included in the following sample.
<CodeBlockWrapper>
<CodeBlock
className="language-json"
children={`
"attributes": {
"vault": {
"setup_token": "9CF1C63VB2681719",
"status": "APPROVED",
"links": [
{
"href": "https://api-m.paypal.com/v3/vault/payment-tokens",
"rel": "create-payment-token",
"method": "POST"
},
{
"href": "https://api-m.paypal.com/v3/vault/setup-tokens/9CF1C63VB2681719",
"rel": "get-setup-token",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "up",
"method": "GET"
}
]
}
}
`}
/>
</CodeBlockWrapper>
There are two ways to move forward with saving the payment source when an <code>APPROVED</code> status is returned (neither of which requires any input from the payer to complete):
1. Following the <code>create-payment-token</code> link from the links array returned, and using the <code>setup_token</code> to generate a payment token that can be used in future transactions. Details for how to accompish this can be found [here](/beta/vault/purchase-later/paypal/#link-createpaymenttoken).
1. Alternatively, the same goal can be accomplished by subscribing to the <code>VAULT.PAYMENT-TOKEN.CREATED</code> webhook. The Vault API will keep working to vault the payment source even after the Orders API returns its response and the Vault API will send a webhook after the payment source has been vaulted. An example of the <code>VAULT.PAYMENT-TOKEN.CREATED</code> webhook payload is shown in the following sample:
<CodeBlockWrapper>
<CodeBlock
className="language-json"
children={`
{
"id": "WH-54U753518P812093G-3GD69489S94654234",
"event_version": "1.0",
"create_time": "2022-10-13T23:04:17.378Z",
"resource_type": "payment_token",
"resource_version": "3.0",
"event_type": "VAULT.PAYMENT-TOKEN.CREATED",
"summary": "A payment token has been created.",
"resource": {
"create_time": "2018-12-11T21:21:49.000Z",
"update_time": "2018-12-11T21:21:49.000Z",
"id": "ckfmsf",
"customer": {
"id": "4029352050"
},
"payment_source": {
"venmo": {
"description": "Description for Venmo to be shown to Venmo payer",
"shipping": {
"name": {
"full_name": "John Doe"
},
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "Building 17",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
},
"usage_pattern": "IMMEDIATE",
"usage_type": "MERCHANT",
"customer_type": "CONSUMER",
"email_address": "john.doe@example.com",
"payer_id": "VYYFH3WJ4JPJQ",
"user_name": "johndoe"
}
},
"links": [
{
"rel": "self",
"href": "https://api-m.paypal.com/v3/vault/payment-tokens/ckfmsf",
"method": "GET"
},
{
"rel": "delete",
"href": "https://api-m.paypal.com/v3/vault/payment-tokens/ckfmsf",
"method": "DELETE"
}
]
},
"links": [
{
"href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-54U753518P812093G-3GD69489S94654234",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-54U753518P812093G-3GD69489S94654234/resend",
"rel": "resend",
"method": "POST"
}
]
}
`}
/>
</CodeBlockWrapper>
As seen above, the <code>resource.id</code> field is the vault id, and <code>resource.customer.id</code> is the PayPal generated customer ID.
## 6. Paying with saved Venmo button
At this step, you should have successfully completed a transaction with a vaulted Venmo button, and stored the PayPal generated customer ID in your system. On a returning payer flow on the checkout page, the Javascript SDK should be initialized with the PayPal generated customer ID as described in steps 1 and 2 above. The Javascript SDK will now render the Venmo button with the payer's Venmo id displayed which will enable the expedited checkout flow.
## 7. Test your integration
Run the following tests in the PayPal production to ensure vaulting the payment method is set up correctly.
### Save payment method
1. On your checkout page, click the Venmo button.
1. Log in to the payer account and approve the payment. Refer to the [Venmo testing guidelines](/docs/checkout/pay-with-venmo/integrate/#link-testandgolive) for more details.
1. Capture the transaction.
1. Store the Paypal generated customer id in your system.
1. Log in to [production](https://www.paypal.com/) with your merchant account and verify the transaction.
1. Refresh the page that contains the Venmo button, ensuring the Javascript SDK is intialized with the Paypal generated customer id as mentoned in step 1 and 2 above.
1. Ensure the Venmo button displays the payer's Venmo id.
1. Ensure that the payment method you just saved is visible with the other buttons.
1. Click the Venmo button again to test return payer flows.
You've completed the steps to vault a Venmo payment method.
## 8. Next steps
* [Test and go live](/docs/business/test-and-go-live/) with this integration - ignore the references to the sandbox environment as it is not applicable for Venmo.
* You can [create orders](/docs/api/orders/v2/#orders_create) the usual way (without the <code>payment_source.venmo.attributes.vault</code> mentioned in step 3 for a returning buyer.
* You can [get a payment token](/api/limited-release/payment-tokens/v3/#payment-tokens_get), [list all payment tokens](/api/limited-release/payment-tokens/v3/#payment-tokens_payment-tokens), [delete a payment token](com/api/limited-release/payment-tokens/v3/#payment-tokens_get), and more with the Payment Method Tokens API.
## 9. Go live
1. Go to [paypal.com](https://www.paypal.com) and sign in with your business account.
1. Go to **Account Settings** > **Payment Preferences** > **Save PayPal and Venmo payment methods**.
1. In the Save PayPal and Venmo payment methods section, select **Get Started**.
1. After you submit the details on the Profile collection, your status will change to "Your eligibility to save customer PayPal and Venmo payment methods is under review". It might be approved instantly as well.
1. Based on information provided in the profile collection of the Business Account, you might see a status like **Denied**, **Success**, or **Need more information**. Once the information is vetted, you get a **Success** status.
Sign in with Wallet
Connect another wallet