# 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](https://developers.bead.xyz/payments/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: * [Quick Start](https://developers.bead.xyz/quick-start) * [Create Payment](https://developers.bead.xyz/payments/create-payment) * [Payment Statuses](https://developers.bead.xyz/payments/payment-statuses) * [Receipts](https://developers.bead.xyz/payments/receipts) * [Payment Webhooks](https://developers.bead.xyz/payments/payment-webhooks) and [Webhook Event Reference](https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference) ### 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 `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, 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/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. Create Payment also documents the optional tender preselection behavior available for advanced integrations. 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 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 * Create your first payment in Sandbox using [Quick Start](https://developers.bead.xyz/quick-start) * Add webhooks and validate event handling using the [Webhook Event Reference](https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference) * Implement a status check flow using [Payment Statuses](https://developers.bead.xyz/payments/payment-statuses) * Use [Reporting ](https://developers.bead.xyz/reporting)and [Settlement ](https://developers.bead.xyz/settlement)to build reconciliation and operational dashboards