Last updated: November 17, 2026
Save Venmo accounts to charge payers after a set amount of time. For example, offer a free trial and charge payers after the trial expires. Payers don't need to be present when charged, and no checkout is required.
Customers with a saved Venmo account can:
Venmo is available only in the US.
Save a Venmo account without a purchase if you want customers to:
Use this server-to-server integration when you need full server-side control of the vaulting flow and don't render the PayPal JavaScript SDK. For example, use it to add Venmo to an existing server-driven checkout. To let the SDK manage app switch and payer approval, see Save Venmo for purchase later with JavaScript SDK v5.
Complete the following before you start:
return_url after the payer approves in Venmo.Your server calls the Vault and Orders APIs directly, and your application redirects the payer.
PayPal requires Risk Data Acquisition (RDA) to reduce fraud. Collect device data with FraudNet and Magnes. Send the client metadata ID (CMID) that FraudNet used in the PayPal-Client-Metadata-Id header of the Create Order request for each customer-initiated transaction (CIT) on a saved Venmo payment token. The payer isn't present when you charge, so store the CMID from the session that collected the device data, and send it with the charge. A CMID with no matching FraudNet session doesn't link the charge to device data. Requests without RDA data are likely to be declined because of insufficient risk identifiers.
Vault without purchase saves a Venmo account as a payment method without a transaction. When you save with a purchase, the order captures a payment while it saves the method. Without a purchase, no order or capture happens at the time of saving.
return_url.The following table compares the two flows:
| Aspect | Save with a purchase | Save without a purchase |
|---|---|---|
| API flow | Create order, capture, and receive a vault token | Create setup token, then create payment token |
| Payer consent | During checkout approval | On a dedicated consent screen |
| Payment at time of saving | Yes, PayPal captures a payment | No |
| Button label | Pay Now or Continue | Confirm |
Call POST /v3/vault/setup-tokens to start the vaulting flow without a purchase. Set the payer-facing instruction in user_action. The user_action field replaces the deprecated vault_instruction field. Integrations that still send vault_instruction continue to work.
Replace the following values:
ACCESS-TOKEN: Your app's access token.BN-CODE: Your PayPal Attribution ID. Platform integrations only.AUTH-ASSERTION-JWT: Your PayPal-Auth-Assertion token. Platform integrations only.REQUEST-ID: A unique alphanumeric string, such as a timestamp.user_action: The action value for your flow. For accepted values, see the Payment Method Tokens API reference.return_url and cancel_url: URLs on your site that handle the payer's return.merchant_customer_id: Optional. Your own customer identifier, to simplify mapping between your system and PayPal.Platforms and marketplaces that save Venmo accounts for their sellers should use the Platform integration tab.
Merchants that integrate directly with PayPal should use the Merchant integration tab.
Use the same tab for every request.
curl -v -X POST https://api-m.paypal.com/v3/vault/setup-tokens \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-Id: BN-CODE' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
-H 'PayPal-Request-Id: REQUEST-ID' \
-d '{
"payment_source": {
"venmo": {
"usage_type": "PLATFORM",
"customer_type": "CONSUMER",
"permit_multiple_payment_tokens": false,
"experience_context": {
"brand_name": "Merchant Store",
"user_action": "SETUP_NOW",
"return_url": "https://merchant.com/vault-return",
"cancel_url": "https://merchant.com/vault-cancel",
"app_switch_context": {
"source": "NATIVE_APP"
}
}
}
},
"customer": {
"merchant_customer_id": "your-customer-id-123"
}
}'A status of PAYER_ACTION_REQUIRED means the payer needs to authorize the vault connection in Venmo. Redirect the payer to the payer-action link.
{
"id": "setup_ABC123",
"status": "PAYER_ACTION_REQUIRED",
"payment_source": {
"venmo": {}
},
"links": [
{
"href": "https://api-m.paypal.com/v3/vault/setup-tokens/setup_ABC123",
"rel": "self",
"method": "GET",
"encType": "application/json"
},
{
"href": "https://account.venmo.com/go/web/paypal?vault_token=setup_ABC123&return_flow=AUTO",
"rel": "payer-action",
"method": "GET",
"encType": "application/json"
}
]
}Redirect the payer to the payer-action link from the setup token response. The payer sees a dedicated consent screen to save their Venmo account. No purchase amount appears.
The consent screen shows the following:
The payer's operating system decides whether an app switch happens. The payer-action link is a universal link. When the payer opens it, the operating system checks whether the Venmo app is installed and registered for the link. If so, the operating system opens the Venmo app. Otherwise, it opens the browser.
The app_switch_context.source value controls the behavior:
NATIVE_APP: Attempts an app switch when the Venmo app is installed, and otherwise opens the web flow.DESKTOP_WEB and MOBILE_WEB: Open the web flow, even when the Venmo app is installed.The payer-action link has the same shape for every outcome. Desktop uses the web flow because the Venmo app isn't present.
The return_flow value determines how the payer returns to your site or app:
AUTO (source: NATIVE_APP): The operating system switches the payer back to your return_url or cancel_url after the payer approves or cancels.MANUAL (source: DESKTOP_WEB or MOBILE_WEB): The payer returns to your page or app manually.Before you create a payment token, call GET /v3/vault/setup-tokens/{SETUP-TOKEN-ID} to check the status of the setup token. Platform integrations send the same PayPal-Auth-Assertion and PayPal-Partner-Attribution-Id headers that created the setup token. Replace SETUP-TOKEN-ID with the id from the setup token response, and replace BN-CODE and AUTH-ASSERTION-JWT with the values from the previous request.
curl -v -X GET https://api-m.paypal.com/v3/vault/setup-tokens/SETUP-TOKEN-ID \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-Id: BN-CODE' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT'A successful response returns the setup token with its current status. Continue after the status shows that the payer approved.
After the payer approves, call POST /v3/vault/payment-tokens to exchange the setup token for a permanent payment token. Replace ACCESS-TOKEN and REQUEST-ID with your values, and replace SETUP-TOKEN-ID with the id from the setup token response. Platform integrations also send the same PayPal-Auth-Assertion and PayPal-Partner-Attribution-Id headers that created the setup token. Replace BN-CODE and AUTH-ASSERTION-JWT with the values from the first request.
curl -v -X POST https://api-m.paypal.com/v3/vault/payment-tokens \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-Id: BN-CODE' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
-H 'PayPal-Request-Id: REQUEST-ID' \
-d '{
"payment_source": {
"token": {
"id": "SETUP-TOKEN-ID",
"type": "SETUP_TOKEN"
}
}
}'Store the id (the payment token) and the customer.id (the PayPal-generated customer ID) in your system for future charges.
{
"id": "hg654s1t",
"customer": {
"id": "BygeLlrpZF",
"merchant_customer_id": "your-customer-id-123"
},
"payment_source": {
"venmo": {
"description": "Description for Venmo to be shown to Venmo payer",
"email_address": "payer@example.com",
"user_name": "johndoe",
"account_id": "VYYFH3WJ4JPJQ",
"shipping": {
"name": {
"full_name": "Firstname Lastname"
},
"address": {
"address_line_1": "123 Main St.",
"address_line_2": "Unit 1",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
},
"usage_pattern": "IMMEDIATE",
"usage_type": "MERCHANT",
"customer_type": "CONSUMER",
"name": {
"given_name": "Firstname",
"surname": "Lastname"
},
"address": {
"address_line_1": "123 Main St.",
"address_line_2": "Unit 1",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
}
}
},
"links": [
{
"rel": "self",
"href": "https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t",
"method": "GET",
"encType": "application/json"
},
{
"rel": "delete",
"href": "https://api-m.paypal.com/v3/vault/payment-tokens/hg654s1t",
"method": "DELETE",
"encType": "application/json"
}
]
}To charge the saved account later, call POST /v2/checkout/orders and pass the payment token in payment_source.venmo.vault_id. The payer doesn't need to be present. Send the CMID in the PayPal-Client-Metadata-Id header, as the RDA warning at the start of this page describes.
{
"intent": "CAPTURE",
"purchase_units": [
{
"amount": {
"currency_code": "USD",
"value": "29.99"
}
}
],
"payment_source": {
"venmo": {
"vault_id": "hg654s1t"
}
}
}Subscribe to the following Payment Method Tokens webhook events to track the lifecycle of saved payment methods:
| Event | Description |
|---|---|
VAULT.PAYMENT-TOKEN.CREATED | PayPal created a payment token. |
VAULT.PAYMENT-TOKEN.CREATION-FAILED | PayPal couldn't create a payment token. |
VAULT.PAYMENT-TOKEN.DELETED | A payment token was removed. |
The vault app switch flow adds no new webhook events. For the full list, see Webhook event names.
The following restrictions apply to saving Venmo accounts:
Test in the sandbox before you go live:
https://api-m.sandbox.paypal.com.The sandbox doesn't support subsequent purchases with saved Venmo tokens. See Venmo testing. A failed sandbox charge in the last step of this guide doesn't mean your integration is faulty. Test charging a saved token in the live environment.
Before you go live, complete the following:
Continue with the following:
Save PayPal
Use the Payment Method Tokens API to save PayPal for future payments. Ideal for free trials or delayed charges. No immediate transaction required.
Alternative payment methods
Enable global payments with Alternative payment methods (APMs). Handle currency conversion and ensure smooth transactions by subscribing to the APM webhook event.