---
title: Save Venmo for purchase later with the Payment Method Tokens API
description: Save a payer's Venmo account to the vault without a purchase or an
  SDK, using server-to-server calls to the Payment Method Tokens and Orders v2
  APIs.
---

# Save Venmo for purchase later with the Payment Method Tokens API (/platforms/checkout/save-payment-methods/purchase-later/payment-tokens-api/venmo)



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:

* Be charged for recurring transactions or subscriptions without being present
* Check out on your site without re-entering payment details
* Manage their saved payment connections in Venmo Connected Businesses

## Availability [#availability]

Venmo is available only in the US.

## Use cases [#use-cases]

Save a Venmo account without a purchase if you want customers to:

* Add Venmo to a wallet during account setup for future purchases
* Enroll in recurring billing without an initial charge
* Sign up for a subscription and add Venmo before the first charge
* Start a free trial where billing begins at a future date

## When to use the Payment Method Tokens API [#when-to-use-the-payment-method-tokens-api]

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](/platforms/checkout/save-payment-methods/purchase-later/js-sdk/venmo/).

## Know before you code [#know-before-you-code]

Complete the following before you start:

* Identify each payer uniquely. For example, payers create an account and log in to your site.
* Have a PayPal business account with Venmo enabled and REST API credentials (client ID and secret).
* Turn on **Save PayPal and Venmo payment methods** in **Account Settings** > **Payment Preferences**, and complete vault vetting before you go live.
* Receive a browser or app redirect at your `return_url` after the payer approves in Venmo.

Your server calls the Vault and Orders APIs directly, and your application redirects the payer.

> **Warning:** PayPal requires Risk Data Acquisition (RDA) to reduce fraud. Collect device data with [FraudNet](/limited-release/fraudnet) and [Magnes](/limited-release/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.

## How it works [#how-it-works]

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.

1. Your server creates a setup token to start the vaulting flow.
2. Your application redirects the payer to Venmo to consent to saving their account. The payer opens Venmo with app switch on mobile or with web approval. No purchase amount appears.
3. The payer confirms and returns to your `return_url`.
4. Your server exchanges the approved setup token for a permanent payment token.
5. You charge the saved Venmo account later by referencing the payment token in a Create Order request.

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                                       |

## 1. Create a setup token [#1-create-a-setup-token]

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](/api/rest/requests/#paypal-partner-attribution-id). Platform integrations only.
* `AUTH-ASSERTION-JWT`: Your [PayPal-Auth-Assertion](/api/rest/requests/#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](/api/payment-tokens/v3#setup-tokens).
* `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.

> **Note:** 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.

#### Platform integration

```bash
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"
    }
  }'
```

#### Merchant integration

```bash
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-Request-Id: REQUEST-ID' \
  -d '{
    "payment_source": {
      "venmo": {
        "usage_type": "MERCHANT",
        "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"
    }
  }'
```

### Setup token response [#setup-token-response]

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.

```json
{
  "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"
    }
  ]
}
```

## 2. Redirect the payer to Venmo for consent [#2-redirect-the-payer-to-venmo-for-consent]

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:

* A **Confirm** button
* The merchant name
* The vault instruction text

### App switch eligibility [#app-switch-eligibility]

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.

## 3. Handle the return [#3-handle-the-return]

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.

#### Platform integration

```bash
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'
```

#### Merchant integration

```bash
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'
```

A successful response returns the setup token with its current `status`. Continue after the status shows that the payer approved.

## 4. Create a payment token [#4-create-a-payment-token]

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.

#### Platform integration

```bash
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"
      }
    }
  }'
```

#### Merchant integration

```bash
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-Request-Id: REQUEST-ID' \
  -d '{
    "payment_source": {
      "token": {
        "id": "SETUP-TOKEN-ID",
        "type": "SETUP_TOKEN"
      }
    }
  }'
```

### Payment token response [#payment-token-response]

Store the `id` (the payment token) and the `customer.id` (the PayPal-generated customer ID) in your system for future charges.

```json
{
  "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"
    }
  ]
}
```

## 5. Charge the saved payment method [#5-charge-the-saved-payment-method]

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.

```json
{
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "amount": {
        "currency_code": "USD",
        "value": "29.99"
      }
    }
  ],
  "payment_source": {
    "venmo": {
      "vault_id": "hg654s1t"
    }
  }
}
```

## Webhooks [#webhooks]

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](/api/rest/webhooks/).

## Restrictions [#restrictions]

The following restrictions apply to saving Venmo accounts:

* **Desktop app switch:** Not available. Desktop uses the web redirect flow only.
* **iframes:** Venmo checkout and vaulting can't render in an iframe.
* **Teen accounts:** Not supported. Teen accounts see an error message.

## Test your integration [#test-your-integration]

Test in the sandbox before you go live:

* Call the sandbox API base URL `https://api-m.sandbox.paypal.com`.
* Use sandbox credentials from the Developer Dashboard.
* Test app switch on iOS with the sandbox Venmo app.

The sandbox doesn't support subsequent purchases with saved Venmo tokens. See [Venmo testing](/venmo/test). 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:

* Confirm that PayPal approved vault eligibility in the live environment.
* Configure live API credentials.
* Configure live webhook endpoints.
* Follow the Venmo brand guidelines for the Venmo button and button label placement.
* Test end to end on all supported surfaces.

## Next steps [#next-steps]

Continue with the following:

* [Test and go live](/api/rest/production/) with this integration.
* [Create orders](/api/orders/v2/orders-create) for subsequent or recurring transactions by referencing the saved payment token.
* [Get a payment token](/api/payment-tokens/v3/payment-tokens-get), [list all payment tokens](/api/payment-tokens/v3/customer-payment-tokens-get), or [delete a payment token](/api/payment-tokens/v3/payment-tokens-delete) with the Payment Method Tokens API.

## See also [#see-also]

* [Orders v2 API reference](/api/orders/v2)
* [Payment Method Tokens API reference](/api/payment-tokens/v3)
* [Save Venmo with the JavaScript SDK (save during purchase)](/platforms/checkout/save-payment-methods/during-purchase/js-sdk/venmo/)
