Test with Venmo

Venmo is available for testing on a terminal with type = virtual. In Sandbox, Venmo does not draw funds from a live Venmo account, so you can complete a test payment with any test account details and confirm the wallet redirect and completion flow end to end. No real assets are required.

Use this guide when you want to validate the Venmo wallet flow. For the recommended default end to end test, see Test with Klarna. For a comparison of all test methods, see Choosing a Test Method.

1 – Prerequisites

Item	Notes
Venmo enabled for your Sandbox merchant and terminal	Contact developer support if Venmo is not yet activated for your Sandbox environment.
Terminal with type = virtual	Venmo testing applies to terminals with type = virtual, not physical.
Sandbox base URL	https://api.test.devs.beadpay.io
Hosted payment page base	Returned in paymentUrls
Terminal API key	You need the real API key value. The masked API key is not usable.
merchantId and terminalId	Must match the terminal API key you were issued.
Webhook endpoint (recommended)	Publicly reachable and registered in the Bead dashboard.

Authentication note: Payments endpoints use header based authentication. Send your API key as X-Api-Key on every request.

2 – Create Payment Request

Send a POST /Payments/crypto to generate the hosted checkout URL. On a terminal with type = virtual, include refundEmail and a customer object.

Required headers:

• X-Api-Key: {apiKey}

• Content-Type: application/json

To present Venmo as the tender, include venmo in tenderTypes.

Example request

curl -s -X POST "https://api.test.devs.beadpay.io/Payments/crypto" \
-H "Content-Type: application/json" \
-H "X-Api-Key: {apiKey}" \
-d '{
"merchantId": "{merchantId}",
"terminalId": "{terminalId}",
"requestedAmount": 1,
"refundEmail": "[e-mail]",
"tenderTypes": ["venmo"],
"customer": {
"firstName": "Jordan",
"lastName": "Reed",
"email": "[e-mail]",
"address": "456 Market St",
"address2": "Suite 210",
"city": "Chicago",
"state": "IL",
"postalCode": "60601",
"countryCode": "US"
}
}'

Example response:

{
"paymentId": "pay_c10b29e3c8104e0f8dc139c20d9eeb6c",
"trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
"paymentUrls": [
"https://pay.qa.beadpay.io/crypto?paymentPageId=a12b34c56d789e01"
]
}

Save these values:

• paymentUrls[0] for the hosted checkout URL

• paymentId your primary lookup key for status checks, webhooks, reporting, and support

3 – Launch Hosted Payment Page

Use paymentUrls[0] to launch checkout.

Option	Details
Redirect	Redirect the shopper's browser to the hosted page URL.
Embed	Load the hosted page URL in an iframe inside your site.

The shopper now sees Bead's hosted payment page.

4 – Select Venmo and Open Venmo Checkout

1. In the Bead hosted UI, select Venmo as the payment method.

2. Bead presents the Venmo flow. Venmo redirects to the Venmo app, with a QR code fallback available.

How the tester can open Venmo checkout:

• On mobile, follow the redirect into the Venmo app.

• On desktop, scan the QR code with a phone, or use the QR fallback to open the Venmo flow.

5 – Complete Venmo Sandbox Checkout

Complete the Venmo flow using test account details. Because Sandbox does not draw funds from a live Venmo account, you can register and use any test account to complete the payment. No real balance is used and no live wallet is charged.

Confirm the exact Sandbox test account values with developer support if your environment requires a specific test account. In most Sandbox configurations, any well formed test account details will complete the flow.

Follow the Venmo prompts until the shopper is returned to your redirectUrl, if you provided one.

6 – Verify Result

Option A: Webhook verification

Confirm your webhook endpoint receives a payment event indicating completion. Look for a status field that indicates the payment is completed.

Option B: API status check (optional)

Endpoint: GET /Payments/{paymentId}/tracking

curl -s -X GET "https://api.test.devs.beadpay.io/Payments/{paymentId}/tracking" \
-H "X-Api-Key: {apiKey}" \
-H "Accept: application/json"

What to confirm:

• The response shows the payment in a completed state.

• Amount fields reflect a successful payment for the requested amount.

Production eligibility

Sandbox does not enforce Venmo consumer eligibility, but production does. In production, Venmo requires a consumer who is:

• Physically located in the United States

• Using a US based phone number

• 18 or older

• On Venmo app version 7.38.2 or newer

See Which consumers can use Klarna, PayPal, and Venmo? for full details.

Troubleshooting

• Venmo does not appear as a tender option. Venmo may not be enabled for the Sandbox merchant or terminal, or the terminal is not type = virtual. Confirm enablement and terminal type with developer support.

• 401 Unauthorized. The API key is missing or invalid, or the header name is wrong. The header must be exactly X-Api-Key.

• 403 Forbidden. The API key is valid but not permitted for the merchantId or terminalId in your request. Confirm the IDs match the credential set you were issued and that you are using the correct environment.

• Validation error on payment creation. On a terminal with type = virtual, confirm you included refundEmail and a complete customer object.

• Redirect does not happen. Confirm you set a valid redirectUrl. If not provided, Bead will display a hosted confirmation screen instead of redirecting.

Next Steps

• Test different amounts and run cancellation or expiry scenarios.

• On a terminal with type = virtual, you can also validate Test with PayPal.

• Validate your production readiness using webhooks plus status checks and avoid tight polling loops.

Related

• Choosing a Test Method

• Alternative Payments

• Which consumers can use Klarna, PayPal, and Venmo?