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 short Onboarding path note below 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 (OIDC token endpoint).

POST {identity_base_url}/realms/{realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=password
client_id={client_id}
client_secret={client_secret_if_applicable}
username={username}
password={password}
scope={optional}

Example curl:

curl -s -X POST "{identity_base_url}/realms/{realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&client_id={client_id}&username={username}&password={password}"

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

2) Create a payment (minimal)

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

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 may vary by tender):

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

Capture paymentId or trackingId and the hostedUrl.

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.

4) Confirm the result

Poll or use a webhook. Poll:

GET https://api.test.devs.beadpay.io/Payments/tracking/{trackingId}
Authorization: Bearer {access_token}

Example response:

{
  "trackingId": "trk_01J73V2E6S8B1H3Z2D",
  "status": "CAPTURED",
  "amount": 199.99,
  "currency": "USD"
}

Webhook (optional): register a webhook once and rely on events (authorized, captured, refunded, failed). Verify the signature, return 200 OK, and retry on non-2xx.

5) Next steps

  • Refunds and voids

  • Reconciliation and settlement exports

  • Tender-specific options (Klarna, PayPal, Venmo, Alipay, WeChat Pay, Cash App)

Onboarding path (short version)

This is for partners who will submit merchant applications programmatically.

  1. Authenticate (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 emailed 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.

Conventions

  • JSON for request and response bodies.

  • ISO 8601 timestamps in UTC.

  • Use idempotency keys on POSTs you may retry.

  • Standard error payloads include a type, title, status, and trace identifier.

Troubleshooting

  • Can’t authenticate: verify realm, client_id, and user credentials; check clock skew.

  • Hosted page won’t load: confirm you’re passing the token on create and using the returned hostedUrl.

  • No status change: confirm you are polling the correct trackingId or that your webhook endpoint is reachable and returning 200 OK.

PreviousIntroductionNextAuthentication

Last updated