Create Payment

Use the Payments API to generate a hosted payment URL that you can embed or open in a browser. Your application initiates the payment, then the customer completes checkout on Bead’s hosted page.

Because Payments are authenticated with a terminal API key, you should create payments from your backend (recommended). Avoid placing your API key in front end or mobile client code.

Overview

  • Endpoint: POST /payments/crypto (Sandbox base https://api.test.devs.beadpay.io)

  • Supports crypto and digital wallet tenders

  • Returns one or more hosted payment URLs you can embed or open

  • Optionally redirects the shopper to redirectUrl

  • Optional per payment webhooks via webhookUrls, in addition to the terminal’s default webhook

For an end to end sandbox flow, see Quick Start.

Step 1: Authenticate (preferred)

Payments use header based authentication with a terminal API key.

apiKey is the secret credential used to authenticate requests. maskedApiKey is a display value and cannot be used to authenticate. Send apiKey on every request using the X-Api-Key header.

Required headers

  • X-Api-Key: {apiKey}

  • Content-Type: application/json

Step 2: Create a hosted payment URL

Send a request to create a payment. The response includes trackingId, paymentPageId, and paymentUrls.

Endpoint

POST https://api.test.devs.beadpay.io/payments/crypto

Headers

  • X-Api-Key: {apiKey}

  • Content-Type: application/json

Example request body (minimal)

Example request body (expanded)

Example response

Key fields

  • terminalId Terminal identifier in Bead. Determines device level settings such as tender configuration and terminal default webhook.

  • merchantId Merchant identifier. Used for reporting and settlement.

  • requestedAmount Amount in the requested currency. For simple tests, use whole numbers in USD.

  • paymentUrlType Type of payment URL. Common value is web.

  • reference Merchant side reference such as an order or invoice number.

  • description Description that may be shown to the customer and in reporting.

  • customer Optional customer object. If you include any customer field, all required fields must be populated. See the conditional customer data rule below.

  • redirectUrl Optional URL Bead will redirect to after the customer completes or cancels checkout.

  • emailReceipt, smsReceipt, refundEmail Optional receipt and refund contact settings.

  • webhookUrls Optional array of additional webhook endpoints for this payment.

Webhooks

If you include webhookUrls, Bead sends payment lifecycle events to both:

  1. The terminal’s default webhook

  2. Each URL in the webhookUrls array

Configure at least one webhook endpoint before you depend on webhooks in production. See Payment Webhooks for payload and retry details.

Conditional customer data rule

If any field inside customer is sent, all of these fields become required:

  • firstName

  • lastName

  • email

  • address

  • address2

  • city

  • state

  • postalCode

  • countryCode

Omitting any of these when a customer object is present results in 400 Bad Request with a validation error.

If you do not want to send complete customer data, omit the customer object entirely.

Step 3: Present the hosted page

Use the first URL in paymentUrls to start checkout.

Common patterns:

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

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

Redirect behaviour:

  • If redirectUrl is provided: After success or cancel, Bead redirects the browser to redirectUrl and includes context in the query string. Use this to show your own confirmation page.

  • If redirectUrl is not provided: Bead displays a hosted confirmation page that indicates success or cancellation.

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

Step 4: Confirm payment status

You can confirm payment status using webhooks or polling.

Option A: Webhooks (recommended)

  • Configure a terminal level webhook and optionally supply webhookUrls per payment.

  • Your server receives JSON payloads whenever statusCode changes.

  • Respond with 200 OK as soon as you have persisted or queued the event.

Option B: Polling

Endpoint

GET https://api.test.devs.beadpay.io/payments/tracking/{trackingId}

Headers

  • X-Api-Key: {apiKey}

  • Accept: application/json

Example curl

Use the trackingId returned from the Create Payment response.

Typical 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 full status details, see Payment Statuses.

Troubleshooting

  • 401 Unauthorized

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

  • Hosted page will not load

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

    • Confirm the terminal is configured for at least one tender in the environment you are testing.

  • No status change

    • Confirm you are polling the correct trackingId.

    • If using webhooks, confirm your endpoint is reachable and returns HTTP 200 quickly.

Next steps

After you can create and complete a payment in Sandbox:

  • Configure Payment Webhooks and verify your endpoint receives status events.

  • Use Payment Statuses for ad hoc queries and troubleshooting.

  • Explore Reporting and Settlement to build payment history and reconciliation jobs.

  • When ready for Production, request production credentials and switch API base URLs to production.

Legacy authentication (supported for existing integrators)

Some existing integrations authenticate Payments using OAuth 2.0 password grant with a terminal username and password. New Payments integrations should use the terminal API key method described above.

If you are using legacy OAuth for Payments, obtain an access token using the password grant and send Authorization: Bearer {access_token} on Payments requests. See the Authentication page for token endpoint details, realms, and refresh token usage.

Legacy token request example

PreviousPaymentsNextPayment Statuses

Last updated