Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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. By default, Bead handles hosted tender selection based on the tenders enabled for the terminal. For advanced integrations that want a more tailored shopper journey, payment creation can also optionally preselect a specific tender or constrain the hosted experience to a specific tender subset. This optional behavior is documented on Create Payment.

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:

Authentication

Payments use header-based authentication with a terminal API key.

Preferred for new integrations

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

  • The API key is the secret credential

  • The masked API key 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. By default, the hosted page manages tender selection for the shopper. Advanced integrations can optionally preselect a tender or tender subset at payment creation time when they want a more tailored entry point.

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 paymentId.

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: paymentId, trackingId, paymentUrls

Go to Create Payment for request fields, examples, terminal type guidance, tender preselection behavior, 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

If you do not send optional tender preselection fields, the hosted page uses the terminal's normal eligible tender-selection experience. If you do send them, the hosted page can take the shopper directly into a dedicated tender flow or a curated tender subset.

Confirm completion

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

You have two options:

  • Webhooks, recommended for production

  • Polling GET /Payments/{paymentId}/tracking 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. Create Payment also documents the optional tender preselection behavior available for advanced integrations.

Payment status

Check payment status using a simple API call by paymentId. 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

  • Sandbox uses Bead's test API environment, test merchant configuration, test credentials, and hosted test payment experience.

  • Bead Sandbox crypto payments use live blockchain networks. Crypto test payments require real assets and real network fee tokens. Keep test amounts small.

  • For tender-specific testing guidance, including supported wallets, fee tokens, and minimum payment amounts, see Test Crypto Transactions and Crypto Testing and Fees.

Production

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

See Sandbox and production URLs for environment switching guidance.

Security and reliability best practices

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

  • Treat the API key like a password. Store it 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. The header must be exactly X-Api-Key.

403 Forbidden

Request authenticated, but the API key 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