> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/payments/payment-status-response-examples.md). # Payment Status Response Examples This page provides representative payment status payloads for common Bead payment outcomes. The same status payload shape is used when you retrieve a payment status directly and when Bead sends a payment status webhook to your system. Use these examples when mapping Bead payment outcomes to your internal order, invoice, or support states. ### Status payload references Use the tracking endpoint when you need to check the current status of a specific payment on demand. ``` GET /Payments/{paymentId}/tracking X-Api-Key: {apiKey} Accept: application/json ``` Bead also sends payment status webhook events to the configured webhook URL for the terminal or payment. Your webhook handler should process the request body using the same status payload structure shown in the examples below. ``` POST {yourWebhookUrl} Content-Type: application/json ``` ### Payload shape The status payload includes identifiers, the current payment state, amount information, reclaim progress, and optional merchant-supplied metadata. ```json { "paymentId": "string", "trackingId": "string", "paymentCode": "string", "statusCode": "created | processing | completed | overpaid | underpaid | expired | abandoned | invalid | cancelled", "tenderType": "string", "amounts": { "requested": { "inPaymentCurrency": { "amount": 0, "currency": null }, "inRequestedCurrency": { "amount": 0, "currency": { "id": 1, "code": "USD", "name": "US Dollar", "symbol": "$" } } }, "paid": { "inPaymentCurrency": { "amount": 0, "currency": null } } }, "reference": "string", "description": "string", "receivedTime": "2026-05-29T17:10:01Z", "terminalId": "string", "merchantId": "string", "errorMessage": null, "originalSenderAddress": null, "conversions": [], "refundLifecycleStatus": "notStarted | emailSent | customerClaimed | processing | completed | failed | rejected", "refundInitiatedAt": null, "refundCompletedAt": null, "refundFailureReason": null } ``` ### Field notes | Field | Description | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paymentId` | Bead payment identifier returned when the payment was created. Use it as the primary identifier for the whole payment lifecycle, including `GET /Payments/{paymentId}/tracking`. | | `trackingId` | Legacy identifier, deprecated but still returned for backward compatibility. Do not use it for new integrations. | | `paymentCode` | Short payment code shown on the hosted payment page and in reporting. | | `statusCode` | Current Bead payment status. Use this as the source of truth for payment state. | | `tenderType` | The tender actually used to pay, once known. | | `amounts.requested.inRequestedCurrency` | Amount requested from the customer in the original requested currency. | | `amounts.requested.inPaymentCurrency` | Amount expected in the selected payment currency, when available. | | `amounts.paid.inPaymentCurrency` | Amount actually received in the payment currency. | | `reference` | Optional merchant-supplied reference from the original payment request. | | `description` | Optional merchant-supplied description from the original payment request. | | `receivedTime` | Timestamp associated with the status event or update. | | `terminalId` | Terminal associated with the payment. | | `merchantId` | Merchant associated with the payment. | | `errorMessage` | Additional error context when available. Usually null for normal lifecycle states. | | `originalSenderAddress` | The sending wallet address for crypto payments, when available. | | `conversions` | Currency conversion details, when applicable. | | `refundLifecycleStatus` | Where a reclaim return to the payer stands. A value of `null` means the same as `notStarted`. See [Tracking Reclaim Status](/reference-guide/payment-scenarios/tracking-reclaim-status.md). | | `refundInitiatedAt` | When Bead first emailed the payer reclaim instructions or the payer started a claim. | | `refundCompletedAt` | When Bead confirmed the return to the payer. | | `refundFailureReason` | Populated when a return attempt failed. | ### Status examples covered | Status | Outcome | What the example shows | | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `created` | Pending | Payment record created; no funds confirmed yet | | `processing` | Pending | Payment is in progress; the outcome is not yet known | | `completed` | Paid | Customer paid the requested amount. Final status | | `overpaid` | Paid | Customer sent more than the requested amount. The requested amount settles and the excess is returned. Final status | | `underpaid` | Not paid | Customer sent less than the requested amount. Treat as declined. Final status | | `expired` | Not paid | Payment expired before completion. Final status | | `cancelled` | Not paid | Payment was cancelled before completion. Final status | | `invalid` | Not paid | Irregular or unsupported payment event requiring exception handling. Final status | | `abandoned` | Not paid | Payment was created but never started, and was closed by Bead. Final status | ### Created A `created` payment has been created, but the customer has not completed payment and no funds have been confirmed. ### Processing A `processing` payment is still in progress. The customer or wallet flow may have started, but the outcome is not yet known. Do not treat `processing` as a paid payment. ### Completed A `completed` payment indicates that the customer paid the requested amount. Fulfill the order. ### Overpaid An `overpaid` payment means the customer sent more than the requested amount. The `requested` and `paid` objects show the difference between the amount expected and the amount actually received. Treat `overpaid` as a paid payment and fulfill the order. The requested amount settles to the merchant. The excess, `amounts.paid` minus `amounts.requested`, is returned to the payer through the reclaim process. `statusCode` stays `overpaid`. Reclaim progress, including completion, arrives in webhooks as changes to `refundLifecycleStatus`. ### Underpaid An `underpaid` payment means the customer sent less than the requested amount. The `requested` and `paid` objects show the difference between the amount expected and the amount actually received. Treat `underpaid` as a declined payment. Do not fulfill, and offer the customer a new payment. The amount sent is returned to the payer through the reclaim process. `statusCode` stays `underpaid`. Reclaim progress, including completion, arrives in webhooks as changes to `refundLifecycleStatus`. ### Expired An `expired` payment means the payment window expired before the payment completed. ### Cancelled A `cancelled` payment means the payment was cancelled before completion. ### Invalid An `invalid` payment indicates an irregular or unsupported payment event. Examples may include multiple transactions, unsupported assets, compliance blocks, extreme market movement, or other exception conditions. The exact `errorMessage` may vary by cause. ### Abandoned An `abandoned` payment was created, but the customer never started a payment attempt. Bead closes these payments automatically after the hosted payment session lifetime. Nothing was requested, so there is nothing to reclaim. ### Reclaim progress Every status except `created` and `processing` is final. A reclaim does not change `statusCode`. Bead sends a payment webhook each time `refundLifecycleStatus` changes, with the payment's final `statusCode` unchanged. `partiallyRefunded` and `fullyRefunded` are reserved values. See [Tracking Reclaim Status](/reference-guide/payment-scenarios/tracking-reclaim-status.md). ### Implementation guidance When mapping these payloads to your integration: * Use `statusCode` as the primary state indicator * Store `paymentId` with your internal payment, invoice, or order record and use it as the primary key for correlation * Use `paymentId` when calling `GET /Payments/{paymentId}/tracking` * Use `paymentId` to correlate Create Payment responses, webhook events, reporting records, and support workflows * Do not build new logic on `trackingId`. It is a legacy identifier kept for backward compatibility * Compare `amounts.requested` and `amounts.paid` when handling `overpaid` or `underpaid` * Treat `processing` as pending * Treat `completed` and `overpaid` as paid for the requested amount, and fulfill * Treat `underpaid`, `expired`, `invalid`, `cancelled`, and `abandoned` as not paid * Treat later reclaim webhooks as record updates. Do not reverse fulfillment * Make webhook processing idempotent. You may receive the same event more than once * If a webhook event is missed, delayed, or received out of order, call `GET /Payments/{paymentId}/tracking` to confirm the current state ### Related pages * [Payment Statuses](/payments/payment-statuses.md) * [Payment Webhooks](/payments/payment-webhooks.md) * [Payment Scenarios](/reference-guide/payment-scenarios.md) * [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.md) * [Tracking Reclaim Status](/reference-guide/payment-scenarios/tracking-reclaim-status.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.bead.xyz/payments/payment-status-response-examples.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.