PayPal - Venmo

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 wallet connector. To accept Venmo through Braintree instead, see Venmo via Braintree.

Venmo is only available for United States merchants, in USD, to buyers in the United States.

Venmo is a redirect payment method, so Embed presents it alongside your other methods and handles the approval popup for you. To integrate directly, see Integration.

Setup

Follow the PayPal setup instructions 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

Integration

If you use Embed, 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.
web: Render the Venmo button inside your own checkout with the PayPal Web SDK v6. See Web: run the SDK yourself.
ios and android: Hand the transaction session to PayPal’s mobile SDK. See 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.

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",
        }
      ),
  }
);

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)

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);

$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;

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",
  }
)

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.

{
  "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 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, not the older Smart Buttons SDK.

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.

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.

POST /payment-service-definitions/paypal-venmo/sessions

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

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.

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

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

// 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.

Create the transaction (see above) inside createOrder, then use its session_token to get the session data. 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.

POST /transactions/:transaction_id/session?token=:session_token

{
  "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.

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.

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. 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.

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.

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.

Introduction

Aggregators

Methods

Digital wallets

Anti-fraud

Browse

PayPal - Venmo

Setup

Supported countries

Supported currencies

Capabilities

Integration

Create the transaction

Redirect to the Gr4vy-hosted approval page

Web: run the SDK yourself

iOS and Android

About tokenization

Testing

​Setup

​Supported countries

​Supported currencies

​Capabilities

​Integration

​Create the transaction

​Redirect to the Gr4vy-hosted approval page

​Web: run the SDK yourself

​iOS and Android

​About tokenization

​Testing

Setup

Supported countries

Supported currencies

Capabilities

Integration

Create the transaction

Redirect to the Gr4vy-hosted approval page

Web: run the SDK yourself

iOS and Android

About tokenization

Testing