> ## Documentation Index
> Fetch the complete documentation index at: https://gr4vy.radial-commerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PayPal - Venmo

> Configure Venmo via PayPal as a payment method in Gr4vy.

**PayPal**

Venmo is a digital wallet and payments app owned by PayPal that allows buyers to send and receive money and to pay online retailers. It is available to buyers in the United States and is widely used by mobile-first shoppers.

This connector accepts Venmo through a PayPal Commerce Platform account, using the same credentials as the [PayPal](https://gr4vy.radial-commerce.com/connections/payments/paypal-paypal.md) wallet connector. To accept Venmo through Braintree instead, see [Venmo via Braintree](https://gr4vy.radial-commerce.com/connections/payments/braintree-venmo.md).

> [!WARNING]
>
> Venmo is only available for United States merchants, in USD, to buyers in the United States.

> [!NOTE]
>
> Venmo is a redirect payment method, so [Embed](https://gr4vy.radial-commerce.com/guides/payments/embed/quick-start/overview.md) presents it alongside your other methods and handles the approval popup for you. To integrate directly, see [Integration](#integration).

## Setup

Follow the [PayPal setup instructions](https://gr4vy.radial-commerce.com/connections/payments/paypal.md) before configuring Venmo payments, then ask PayPal to enable Venmo on your PayPal merchant account.

The connector takes the same **Client ID** and **Client secret** as the PayPal wallet connector. You can configure both connectors on the same credentials.

## Supported countries

## Supported currencies

## Capabilities

This list is for guidance only. It doesn't guarantee availability or
create any rights, and the provider may need to enable some features for
your account.

## Integration

If you use [Embed](https://gr4vy.radial-commerce.com/guides/payments/embed/quick-start/overview.md), Venmo needs no integration work. Embed treats it as a redirect payment method, opens the approval page in a popup, and returns the buyer to your checkout.

To integrate directly, set `integration_client` on the transaction to one of the following.

* **`redirect`**: Send the buyer to the `approval_url` Gr4vy returns, and let the Gr4vy-hosted page run PayPal's SDK. See [Redirect to the Gr4vy-hosted approval page](#redirect-to-the-gr4vy-hosted-approval-page).
* **`web`**: Render the Venmo button inside your own checkout with the PayPal Web SDK v6. See [Web: run the SDK yourself](#web-run-the-sdk-yourself).
* **`ios` and `android`**: Hand the transaction session to PayPal's mobile SDK. See [iOS and Android](#ios-and-android).

### Create the transaction

Every flow starts with the same request: `method` set to `venmo`, an `integration_client`, and a `redirect_url` your app can handle. Keep this call server-side. Set the transaction `intent` to match the intent configured on your connection.

The samples below use `web`. Substitute the `integration_client` for the route you are integrating.

```csharp C# theme={"system"}
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "USD",
    Country = "US",
    IntegrationClient = "web",
    Intent = "capture",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "venmo",
          Country = "US",
          Currency = "USD",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);
```

```go Go theme={"system"}
amount := int64(1299)
currency := "USD"
country := "US"
integrationClient := "web"
intent := components.TransactionIntentCapture
method := components.RedirectPaymentMethodCreateMethodVenmo
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  RedirectURL: redirectUrl,
}
paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
  Amount:            amount,
  Currency:          currency,
  Country:           &country,
  IntegrationClient: &integrationClient,
  Intent:            &intent,
  PaymentMethod:     &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil, nil)
```

```java Java theme={"system"}
CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
  .transactionCreate(TransactionCreate.builder()
    .amount(1299L)
    .currency("USD")
    .country("US")
    .integrationClient("web")
    .intent(TransactionIntent.CAPTURE)
    .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
      .method(RedirectPaymentMethodCreateMethod.VENMO)
      .country("US")
      .currency("USD")
      .redirectUrl("https://example.com/callback")
      .build()))
    .build())
  .call();

Transaction transaction = transactionResponse.transaction().orElse(null);
```

```php PHP theme={"system"}
$transactionCreate = new TransactionCreate(
  amount: 1299,
  currency: 'USD',
  country: 'US',
  integrationClient: 'web',
  intent: 'capture',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'venmo',
    country: 'US',
    currency: 'USD',
    redirectUrl: 'https://example.com/callback'
  )
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;
```

```python Python theme={"system"}
transaction: models.Transaction = client.transactions.create(
  amount=1299,
  currency="USD",
  country="US",
  integration_client="web",
  intent="capture",
  payment_method={
    "method": "venmo",
    "country": "US",
    "currency": "USD",
    "redirect_url": "https://example.com/callback",
  }
)
```

```ts TypeScript theme={"system"}
const transaction = await gr4vy.transactions.create({
  amount: 1299,
  currency: "USD",
  country: "US",
  integrationClient: "web",
  intent: "capture",
  paymentMethod: {
    method: "venmo",
    country: "US",
    currency: "USD",
    redirectUrl: "https://example.com/callback"
  }
})
```

The response has a `status` of `buyer_approval_pending`, a `session_token`, and a `payment_method.approval_url`.

```json theme={"system"}
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "status": "buyer_approval_pending",
  "payment_method": {
    "type": "payment-method",
    "method": "venmo",
    "mode": "redirect",
    "approval_url": "https://cdn.sandbox.example.gr4vy.app/connectors/paypal/venmo.html?token=..."
  },
  "method": "venmo"
}
```

The transaction stays `buyer_approval_pending` until the buyer completes approval and your app calls the completion URL. If the Venmo flow fails before that, the transaction remains pending and no error is recorded against it, so do not treat a pending transaction as a failed one. Use [webhooks](https://gr4vy.radial-commerce.com/guides/features/webhooks/overview.md) to follow the final status rather than relying on the buyer returning.

### Redirect to the Gr4vy-hosted approval page

Use this to offer Venmo without adding the PayPal JS SDK to your checkout. Create the transaction with `integration_client` set to `redirect`, then send the buyer to the returned `payment_method.approval_url`. That page loads the SDK and starts the Venmo flow as soon as it opens, then returns the buyer to your `redirect_url`.

Open it in a popup rather than replacing the page. Venmo's flow opens its own window, and this connection is marked as requiring a popup.

### Web: run the SDK yourself

Use this to put a Venmo button inside your own checkout. It uses the [PayPal Web SDK v6](https://developer.paypal.com/sdk/js/v6/), not the older Smart Buttons SDK.

> [!WARNING]
>
> Do not load the Smart Buttons SDK (`www.paypal.com/sdk/js`) and the Web SDK v6 on the same page. The v6 script does not claim the `window.paypal` global when the older SDK already holds it, and attaches itself to `window.paypal.v6` instead. The result is a Venmo button that silently never appears. If your checkout already uses Smart Buttons for PayPal, either move PayPal to v6 as well or load v6 under its own `data-namespace`.

1. On page load, fetch the connection's standalone session to get its PayPal `clientId`. This needs the `transactions.write` scope, so call it from your server. It creates no transaction and makes no call to PayPal.

```sh theme={"system"}
POST /payment-service-definitions/paypal-venmo/sessions
```

Send an empty JSON object as the body:

```json theme={"system"}
{}
```

The response looks like this:

```json theme={"system"}
{
  "type": "payment-service-session",
  "status": "succeeded",
  "response_body": {
    "clientId": "AY-client-id",
    "merchantId": "BN-merchant-id"
  }
}
```

> [!NOTE]
>
> This call is optional. The `clientId` is a static connection value, so if you already have it you can pass it straight to the SDK. The session endpoint exists so you don't have to hard-code or separately distribute the connection's credentials to your frontend. `merchantId` is returned for multi-party setups; the Gr4vy-hosted page does not send one.

2. Load the v6 core script and create an SDK instance scoped to the `venmo-payments` component, then render the SDK's `<venmo-button>`.

```html theme={"system"}
<script async src="https://www.sandbox.paypal.com/web-sdk/v6/core"></script>
<venmo-button type="pay" hidden></venmo-button>
```

```js theme={"system"}
// clientId comes from the standalone session in step 1.
const sdkInstance = await window.paypal.createInstance({
  clientId,
  clientMetadataId: crypto.randomUUID(),
  components: ["venmo-payments"],
  pageType: "checkout",
});

const paymentSession = sdkInstance.createVenmoOneTimePaymentSession({
  onApprove: () => window.location.assign(defaultCompletionUrl),
  onCancel: () => { /* the buyer backed out */ },
  onError: (error) => console.error(error),
});

document
  .querySelector("venmo-button")
  .addEventListener("venmo-click", () =>
    paymentSession.start({ presentationMode: "auto" }, createOrder())
  );
```

`presentationMode: "auto"` lets the SDK choose how to present the flow: an in-page modal, a popup window, or the Venmo app. Pass `"modal"` or `"popup"` to fix it.

3. Create the transaction (see above) inside `createOrder`, then use its `session_token` to get the [session data](https://gr4vy.radial-commerce.com/reference/transactions/get-transaction-session.md). This returns the PayPal `orderId` and a `default_completion_url`. It is meant to be called from the frontend and is not exposed in the SDKs, so call it with a plain request authenticated by the `session_token`.

```sh theme={"system"}
POST /transactions/:transaction_id/session?token=:session_token
```

```json theme={"system"}
{
  "type": "transaction-session",
  "session_data": {
    "clientId": "AY-client-id",
    "orderId": "5O190127TN364715T",
    "returnUrl": "https://api.example.gr4vy.app/transactions/approve/..."
  },
  "default_completion_url": "https://api.example.gr4vy.app/transactions/approve/...",
  "integration_client": "web"
}
```

`start()` takes a *promise* of `{ orderId }`, so return one from `createOrder` and the flow opens on the buyer's click while the order is still being created. Create the order in response to the click rather than ahead of time, so it is fresh when the flow opens.

4. When `onApprove` fires, send the buyer to the `default_completion_url`. Gr4vy finalizes the order with PayPal and then returns the buyer to the `redirect_url` you set on the transaction.

### iOS and Android

Set `integration_client` to `ios` or `android` and use an app deep link (for example `yourapp://`) as the `redirect_url`. The transaction session returns the same `session_data` as the web flow — `clientId`, `orderId` and `returnUrl` — which you hand to PayPal's mobile SDK to collect the buyer's approval. On approval, call the `default_completion_url` to finalize the order.

## About tokenization

Pass `store: true` on a transaction to vault the buyer's Venmo account for future use, together with a buyer so the stored account can be found again. Subsequent payments then charge the stored token without sending the buyer back to Venmo.

The stored Venmo account only becomes usable when PayPal sends the `VAULT.PAYMENT-TOKEN.CREATED` webhook, so subscribe to it as described in [PayPal webhooks](https://gr4vy.radial-commerce.com/connections/payments/paypal.md#webhooks). Until then, the payment method stays `processing`. See [Stored PayPal accounts](https://gr4vy.radial-commerce.com/connections/payments/paypal-paypal.md#stored-paypal-accounts) for how the status changes.

## Testing

PayPal's Venmo sandbox is limited and is built around buyers in the United States. Expect it to be unreliable, and budget time for retries.

* **Create a sandbox Venmo buyer** at [account.ext.live.venmo.com/signup](https://account.ext.live.venmo.com/signup). A successful sign-up does not guarantee a successful payment: an account that authenticates can still fail to complete one.
* **Set both sandbox accounts to the United States** — the business account and the personal account. If either is set elsewhere, the Venmo button does not render at all.
* **No Venmo app is needed.** The sandbox offers a web login on desktop and on mobile web.
* **Pass `sandboxSupport: { enabled: true }`** to `start()` outside production when you run the SDK yourself. The Gr4vy-hosted approval page already does this.
* **`testBuyerCountry: "US"`** on `createInstance` declares a United States buyer. It is sandbox-only and rejected in production, and the Gr4vy-hosted page does not send it.

> [!WARNING]
>
> PayPal can disregard sandbox traffic that originates outside the United States, including traffic behind a VPN. A flow that reaches Venmo's login page can still fail immediately afterwards, on Venmo's own domain, leaving the Gr4vy transaction at `buyer_approval_pending` with no error recorded against it. If you see that, the failure is inside Venmo's hosted flow and not in your integration.

> [!NOTE]
>
> PayPal has acknowledged that Venmo's sandbox has limited functionality, including for buyers inside the United States, and that they are working to improve it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.