Quick Start

This page gets you live in Sandbox quickly. Most integrators start with Payments. If you are here to submit merchant applications, see 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

grant_type=password
client_id={client_id}
username={username}
password={password}
scope={optional}

Example curl (Test / Non-prod)

curl -s -X POST "https://identity.beadpay.io/realms/nonprod/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id={client_id}" \
  -d "username={username}" \
  -d "password={password}"

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)

Post a minimal payment with your chosen tender. For the fastest test, use Klarna.

Sandbox API base

https://api.test.devs.beadpay.io

Request

POST https://api.test.devs.beadpay.io/payments
Authorization: Bearer {access_token}
Content-Type: application/json

Example body (hosted payment flow)

{
  "amount": 199.99,
  "currency": "USD",
  "tenderType": "klarna",
  "orderId": "ord_9aNQy7w4",
  "description": "Test order #9aNQy7w4",
  "returnUrl": "https://merchant.example.com/checkout/return",
  "metadata": { "customerRef": "CUST-1825" }
}

Typical response shape

{
  "paymentId": "pay_01J73V0M3Q2W5YA3K8",
  "trackingId": "trk_01J73V2E6S8B1H3Z2D",
  "hostedUrl": "https://pay.example/session/3c52f0b9",
  "statusCode": "created"
}

Capture paymentId or trackingId and the hostedUrl. The exact response fields depend on tender and environment. For full request and response details, see the Create Payment page.

3) Present the hosted page

Redirect the shopper to hostedUrl or open it in an in-app webview. After completion, your returnUrl will receive the shopper back.

The hosted page handles:

  • Displaying tender options

  • Presenting QR codes or wallet flows

  • Collecting customer inputs required by the tender

4) Confirm the result

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

Poll

GET https://api.test.devs.beadpay.io/payments/tracking/{trackingId}
Authorization: Bearer {access_token}
Accept: application/json

Example response

{
  "trackingId": "trk_01J73V2E6S8B1H3Z2D",
  "statusCode": "completed",
  "amounts": {
    "requested": { "amount": 199.99, "currency": "USD" },
    "paid":      { "amount": 199.99, "currency": "USD" }
  }
}

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

See Payment Statuses for the full list of status values and meanings.

Webhook (optional)

  • Register a payment webhook once per terminal and rely on events such as completed, underpaid, overpaid, and expired

  • Verify the request, return HTTP 200, and implement retries on non-2xx responses in your own code

See Payment Webhooks for payload format, retry guidance, and example handlers.

5) Next steps

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

  • Add refunds and voids where supported

  • 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 are grouped 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 the hostedUrl returned by the API 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