Quick Start

Use this guide to get a Sandbox integration working end to end. Most partners begin with Payments. If you are focused on submitting merchant applications, follow the Onboarding path and then continue in the Onboarding section.

Pick a path

  • Accept a payment (most partners start here)

  • Submit a merchant application (onboarding integrators)

Before you begin

  • Get Sandbox credentials for your team

  • Confirm your environment base URLs and identity realm

  • Choose an HTTP client (curl, Postman, or your SDK)

Payments path

1) Authenticate

Request an access token using OAuth 2.0 (OpenID Connect token endpoint).

Token URLs

  • Test / Non-prod https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token

  • Production https://identity.beadpay.io/realms/prod/protocol/openid-connect/token

Form fields

Example curl (Test / Non-prod)

The response contains access_token. Use it as a Bearer token for all API calls.

For grant types, token fields, and refresh flows, see the Authentication section.

2) Create a payment (minimal)

Create a hosted payment using the Payments API. For a fast test, configure your Sandbox merchant or terminal to support Klarna, then use it as the tender presented on the hosted page.

Sandbox API base

Request

Example body (hosted payment flow)

This example shows a minimal CryptoPaymentRequest with a single cart item and a webhook.

Key points:

  • merchantId and terminalId identify the merchant and terminal in Bead

  • requestedAmount is the amount in the requested currency (for simple tests, use whole numbers in USD)

  • cartItems must contain at least one item, with id, quantity, and price

  • redirectUrl is optional and controls where Bead sends the browser after checkout

  • emailReceipt, smsReceipt, and webhookUrls are optional, but recommended in real integrations

Typical response shape

The POST /payments/crypto endpoint returns a CryptoPaymentResponse that includes a tracking identifier, a payment page identifier, and one or more hosted payment URLs.

For a basic flow:

  • Store trackingId to check status later

  • Store paymentPageId if you plan to use Payment Pages specific endpoints

  • Use the first entry in paymentUrls as the hosted payment URL in your application

For full request and response details, see the Create Payment page.

3) Present the hosted page

Redirect the shopper to the hosted payment URL, or open it inside your application.

Use the first URL in the paymentUrls array (or whichever you choose) to begin checkout.

Common patterns:

  • Web or SPA Embed the URL in an iframe or open it in a new browser tab or window.

  • Native app Load the URL in an in app browser or webview.

Redirect behavior:

  • If redirectUrl is provided, Bead redirects the browser to redirectUrl after success or cancel and appends context in the query string. You can use this to show your own confirmation page.

  • If redirectUrl is not provided, Bead shows a hosted confirmation page indicating success or cancellation.

Regardless of redirect behavior, you should always confirm the final status via webhooks or status polling before shipping goods or granting access.

4) Confirm the result

You can confirm the result by polling or by using a webhook.

Poll

Example response

Key statuses:

  • created and processing while the customer is paying

  • completed when the payment has fully succeeded

  • underpaid, overpaid, expired, invalid, or cancelled for non happy path outcomes

For the full set of status values and their meanings, see Payment Statuses.

Webhook (optional)

  • Instead of polling, you can configure Payment Webhooks so that your system is notified whenever statusCode changes.

    • Register a payment webhook at the terminal level and optionally send webhookUrls in the payment request

    • Receive JSON payloads for status transitions such as completed, underpaid, overpaid, and expired

    • Respond with HTTP 200 as soon as you persist or queue the event

    See Payment Webhooks for payload format, retries, and handler examples.

5) Next steps

Once you can create and complete a payment in Sandbox and confirm the result, you can:

  • Build reconciliation and settlement exports using Reporting and Settlement

  • Explore tender specific options such as Klarna, PayPal, Venmo, Alipay, WeChat Pay, and Cash App

  • Use Reporting (Merchant, Partner, and Terminal Payments) to build dashboards and payment history views

  • Use Settlement (Merchant settlements and Payment settlements) to see how payments roll into settlement batches and when funds are available

Onboarding path (short version)

This path is for partners who will submit merchant applications programmatically.

  1. Authenticate using the same token process as above

  2. POST /merchant-onboarding/application with signer and merchantData

  3. Store applicationId and onboardingUrl from the response; the signer is sent the package automatically

  4. GET /merchant-onboarding/application/{applicationId} or use an onboarding webhook to track status

  5. After approval, use Entity Management to add locations and terminals

The Onboarding section provides full request and response details and example payloads.

Conventions

  • JSON for request and response bodies

  • ISO 8601 timestamps in UTC

  • Idempotency keys on POST operations you may retry

  • Standard error payloads with type, title, status, and trace identifier

See Reference Guide for more details on error formats, rate limits, and core schemas.

Troubleshooting

  • Cannot authenticate

    • Verify realm, client_id, and user credentials

    • Check for clock skew between your environment and the identity provider

  • Hosted page will not load

    • Confirm you are passing a valid Bearer token on create

    • Confirm you are using a URL from the paymentUrls array returned by the create payment response

  • No status change

    • Confirm you are polling the correct trackingId

    • Confirm that your webhook endpoint is reachable and returning HTTP 200 if you are using webhooks

When payments are flowing correctly, move on to the Payments, Reporting, and Settlement sections for deeper integration patterns.

PreviousIntroductionNextAuthentication

Last updated