Payments

Bead provides a unified, secure, and streamlined solution for accepting crypto and digital wallet payments through a hosted payment page. The Payments API is designed to minimize PCI and wallet complexity by keeping tender selection and checkout on Bead’s hosted experience while still giving your application full control over when a payment is created and how you confirm completion.

Payments work together with Reporting and Settlement:

  • Payments create and track individual transactions

  • Reporting provides historical payment views for partners, merchants, and terminals

  • Settlement provides batch level settlement views for reconciliation

Start here

Most integrators start with these pages:

  • Quick Start

  • Create Payment

  • Payment Statuses

  • Payment Webhooks and Webhook Event Reference

Authentication

Payments use header based authentication with a terminal API key.

Preferred (new integrations):

  • Send X-Api-Key: {apiKey} on every Payments request

  • apiKey is the secret credential

  • maskedApiKey is not usable

Legacy support:

  • Existing integrators may still use OAuth password grant and Authorization: Bearer {access_token}

  • New Payments integrations should use the API key method

See Authentication for full details and examples.

Key features

Hosted payment page A secure hosted checkout experience that reduces integration complexity and keeps tender flows off your infrastructure.

Real time webhooks Status change notifications delivered to your backend so you can react as payments move through their lifecycle.

Payment status API A simple GET endpoint to retrieve the latest status for a single payment using its trackingId.

Core workflows

Create a hosted payment URL

Use the Payments API to create a payment and receive the hosted checkout URL.

  • Endpoint: POST /payments/crypto

  • Response: trackingId, paymentPageId, paymentUrls

Go to Create Payment for request fields, examples, and best practices.

Present the hosted page

Use paymentUrls[0] to launch checkout:

  • Web checkout: open in a new tab or embed in an iframe

  • In person or demo flows: display the hosted page and have the customer scan the QR code

Confirm completion

You should confirm the final payment result before fulfilling an order.

You have two options:

  • Webhooks (recommended for production)

  • Polling GET /payments/tracking/{trackingId} for ad hoc checks and support workflows

Go to Payment Statuses for status values and examples.

API capabilities

Hosted payment Generate hosted URLs for customers to complete their payments. The hosted page handles tender selection, crypto and wallet flows, and customer prompts.

Payment status Check payment status using a simple API call by trackingId. Use this for ad hoc checks and troubleshooting.

Webhooks Configure real time status updates delivered to your backend so you do not need to poll the status endpoint.

Environments

Sandbox:

  • Base URL: https://api.test.devs.beadpay.io

Production:

  • Base URL: https://api.devs.beadpay.io

See Sandbox and production URLs for environment switching guidance.

Security and reliability best practices

  • Keep the apiKey server side Create payments from your backend whenever possible. Do not embed the apiKey in browser or mobile apps.

  • Treat apiKey like a password Store in a secret manager or environment variable and avoid logging it.

  • Use webhooks for scale Webhooks reduce polling load and provide faster reaction time.

  • Always verify final status Even if the browser redirects or the hosted UI shows success, confirm status via webhook or tracking endpoint.

Common errors

401 Unauthorized API key missing, invalid, or wrong header name. Header must be exactly X-Api-Key.

403 Forbidden Request authenticated, but the apiKey is not permitted for the merchant or terminal context, or the request is hitting the wrong environment.

See Resolving 403 Forbidden When Creating Payments for a detailed checklist.

Next steps

PreviousAuthenticationNextCreate Payment

Last updated