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

Payment Statuses

Integrators can retrieve the current status of a payment at any time using the paymentId returned when the payment is created. Use this endpoint to verify completion, support customer issues, and keep internal records accurate.

Payment status checks complement webhooks, Reporting, and Settlement. Webhooks notify you when something changes, this endpoint lets you query on demand, and Reporting and Settlement provide historical and settlement views across many payments.

Note for testing: After a reclaim completes, some paths can still return partiallyRefunded or fullyRefunded in statusCode. This is being removed in an upcoming update. Do not build logic around these values. Treat the payment as final, and keep your fulfillment decision from the first outcome. statusCode will stay overpaid or underpaid, and reclaim progress is reported in refundLifecycleStatus.

Overview

Use the payment status endpoint when you want to:

  • retrieve near real time payment status with a simple GET request

  • confirm the outcome of a payment, such as completed, overpaid, underpaid, expired, abandoned, or invalid

  • confirm that a reclaim return has completed, shown by refundLifecycleStatus set to completed

  • identify the tender type actually used to pay, such as bitcoin_Lightning, usdcSolana, paypal, venmo, or klarna

  • troubleshoot or support a single payment without pulling a full history

For ongoing monitoring and reconciliation, prefer webhooks plus Reporting and Settlement instead of frequent polling.

Requesting payment status

Payment status is retrieved by paymentId.

Endpoint

GET /Payments/{paymentId}/tracking

Path parameters

Name
Type
Required
Description

paymentId

string

Yes

Payment identifier returned by the Create Payment response

trackingId is a legacy identifier that is deprecated but still supported for backwards compatibility. The legacy endpoint GET /Payments/tracking/{trackingId} continues to work. New integrations should use paymentId and GET /Payments/{paymentId}/tracking.

Required headers

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

Header
Value

X-Api-Key

{apiKey}

Accept

application/json

Notes:

  • the API key is the secret credential

  • the masked API key is not usable

  • send the full API key value in the X-Api-Key header on every Payments request

Authentication methods for Payment Statuses

Using X-Api-Key

Use X-Api-Key for new Payments integrations.

Using OAuth for legacy Payments integrations

If you are using an existing integration that authenticates Payments through OAuth password grant, send the access token as:

New integrations should use the X-Api-Key method.

Example request

Example response

The tracking endpoint returns the same payload shape as a payment webhook. It includes the reclaim fields (refundLifecycleStatus, refundInitiatedAt, refundCompletedAt, refundFailureReason). It does not include settlement or batch identity (settlementId, batchId, batchPeriod, batchStatus). See "Settlement and batch identity" below for where to get those.

The example below shows an overpaid payment whose payer has been emailed reclaim instructions for the excess. tenderType identifies the tender actually used to pay.

Settlement and batch identity

This endpoint is for payment status only. For settlement and batch identity on a payment, use the Reporting payment history endpoints instead:

Endpoint
Settlement/batch fields returned

GET /Partners/{id}/payments

settlementId, batchId, batchPeriod, batchStatus

GET /Merchants/{id}/payments

settlementId, batchId, batchPeriod, batchStatus

GET /Terminals/{id}/payments

batchId, settlementId, batchStatus (no batchPeriod)

These fields populate as the payment moves through batching and settlement, so expect them to be null until a payment has been batched (and, for settlementId, until the batch has rolled into a settlement). completed and overpaid payments are batched. See Reporting for these endpoints and Settlement for how settlement and batch records work.

Using tenderType

Use the returned tenderType to identify the tender actually used for the payment.

This is especially important when the payment flow presents multiple tender options. For example, an integrator may create one hosted payment session that allows several eligible tenders. When the customer completes the payment with Bitcoin Lightning, the status response returns:

Recommended handling:

  • store tenderType with your order, invoice, or payment record

  • use tenderType for support, analytics, and tender-level reporting

  • use the returned value as the actual tender paid, not only the tender options offered when the payment was created

  • expect tenderType to be populated for paid payments

  • for early or unresolved states, such as created, tenderType may not yet identify a completed tender

BTC Classic and tenderType

BTC Classic refers to Bitcoin on-chain payments. In API responses, use the returned tenderType value to identify the tender actually used for the payment.

For Bitcoin on-chain payments, the tender type is bitcoin. Do not treat bitcoin_Lightning as BTC Classic; Bitcoin Lightning is a separate, faster BTC payment rail.

If your payment flow allows multiple tenders, wait for the returned tenderType when available. If your integration already knows that the customer selected BTC Classic, you can use that local checkout context for customer messaging, but still use statusCode as the source of truth for fulfillment.

Recommended handling:

  • use tenderType: "bitcoin" for BTC Classic / Bitcoin on-chain handling

  • use tenderType: "bitcoin_Lightning" for Bitcoin Lightning handling

  • do not assume all BTC payments have the same customer wait time

  • use completed or overpaid, not processing, as the fulfillment trigger

Status values

Statuses are returned in the statusCode field and use the PaymentStatus enum.

partiallyRefunded and fullyRefunded are reserved values. Reclaim progress and completion are reported in refundLifecycleStatus, not in statusCode. See "Reclaim progress and completion" below.

How crypto amount mismatch happens

In most wallet based crypto payments, the customer scans the QR code to set the destination and then manually enters the amount to send in their wallet app. If the customer mistypes the amount, the payment can end as:

  • overpaid when more than the requested amount is sent. The payment is paid. The requested amount settles to the merchant, and the excess is returned to the payer through Bead's reclaim process.

  • underpaid when less than the requested amount is sent. The payment is not paid. Nothing settles to the merchant, and the full amount sent is returned to the payer through reclaim.

A very small overpayment, within a per tender tolerance set by Bead, is classified as completed instead of overpaid, and no reclaim is offered for the excess.

Status codes

Status code
Description

created

Payment record created, waiting for customer funds. The actual paid tender may not yet be known.

processing

Funds detected and conversion or settlement processing is in progress. The payment is underway, but its outcome is not known yet. For most tenders, this state may be brief. For BTC Classic / Bitcoin on-chain payments, this state may last several minutes or longer while the Bitcoin network confirms the transaction. Do not fulfill based on processing.

completed

Customer sent the requested amount. tenderType identifies the tender actually used. Crypto, if any, has been converted and credited. Paid: fulfill the order. Final status.

overpaid

Customer sent more than requested. Paid: fulfill the order. The requested amount settles to the merchant. The excess is returned to the payer through reclaim. Final status.

underpaid

Customer sent less than requested. Not paid: do not fulfill. Treat it like a declined payment and offer the customer a new payment. The amount sent is returned to the payer through reclaim. Final status.

expired

A payment attempt was started, but no funds were received before the payment window expired. Any funds sent later remain unconverted and must be reclaimed. Final status.

abandoned

The payment was created, but the customer never started a payment attempt, so no quote, deposit address, or checkout was ever issued. Bead closes these payments automatically 24 hours after the payment was created. Final status. See "Abandoned payments" below.

invalid

Irregular event such as multiple transactions, unsupported asset, compliance block, or extreme market movement. Funds remain unconverted and must be reclaimed. Final status.

cancelled

Customer or merchant cancelled the payment. Any funds remain unconverted and may be reclaimed. Final status.

partiallyRefunded

Reserved. Not returned.

fullyRefunded

Reserved. Not returned.

Abandoned payments

A payment is abandoned when it was created but the customer never began paying. For example, your system created a payment and the customer never opened the hosted payment page, or opened it and left without choosing a tender or starting a checkout. No funds were requested or expected, so there is nothing to reclaim.

How this differs from expired:

  • abandoned: no payment attempt was recorded for the payment. Nothing was quoted or issued to the customer.

  • expired: a payment attempt was started (for example a crypto quote, deposit address, or hosted checkout was issued) but was not completed before its window closed.

Because a payment may sit in created for up to 24 hours before Bead closes it, created is not a permanent state for payments that are never paid. Expect these payments to move to abandoned once 24 hours have passed since the payment was created.

Automatic closures and webhooks

Webhook behavior: Bead closes unpaid payments automatically 24 hours after the payment was created, as abandoned or expired. Bead sends a payment webhook for each automatic closure, the same as for any other status change. Both statuses are also available from GET /Payments/{paymentId}/tracking. See Payment Webhooks.

Reclaim progress and completion

When a payment ends as overpaid, underpaid, expired, invalid, or cancelled, Bead returns crypto to the payer through the reclaim process. For overpaid, only the excess is returned. For the other statuses, the full amount received is returned. The progress of that return is on the payment record:

Field
Meaning

refundLifecycleStatus

One of notStarted, emailSent, customerClaimed, processing, completed, failed, rejected. A value of null means the same as notStarted.

refundInitiatedAt

The first time Bead emailed the payer reclaim instructions or the payer started a claim, whichever came first.

refundCompletedAt

When Bead confirmed the return to the payer.

refundFailureReason

Populated when a return attempt failed.

When the return completes, refundLifecycleStatus becomes completed and refundCompletedAt is set. statusCode does not change: an overpaid payment stays overpaid, and an underpaid payment stays underpaid.

These fields are returned by GET /Payments/{paymentId}/tracking, GET /Payments/{paymentId}, payment webhooks, and the merchant and partner payment history endpoints.

Webhook behavior: Bead sends a payment webhook each time refundLifecycleStatus changes, including the change to completed. The statusCode in these webhooks is the payment's final status, unchanged. The webhook goes to the terminal webhook URL and to any webhookUrls set on the payment, using the same payload as other payment webhooks.

See Tracking Reclaim Status for lifecycle values, webhook handling, and example responses.

Final statuses

created and processing are pending. Every other status is final: once a payment reaches it, statusCode does not change.

Status
Outcome
Fulfillment
Reclaim possible

created

Pending

Wait

No

processing

Pending

Wait

No

completed

Paid

Fulfill

No

overpaid

Paid

Fulfill

Yes, the excess only

underpaid

Not paid

Do not fulfill

Yes, the full amount sent

expired

Not paid

Do not fulfill

Yes, if funds arrived

invalid

Not paid

Do not fulfill

Yes, if funds arrived

cancelled

Not paid

Do not fulfill

Yes, if funds arrived

abandoned

Not paid

Do not fulfill

No

Rules for your webhook consumer:

  • Act on the first final status you receive for a paymentId. A payment never returns to created or processing.

  • Expect later webhooks while a reclaim progresses. They carry the same final statusCode with an updated refundLifecycleStatus. Update your reclaim records, but do not reverse the fulfillment decision.

  • A return may never happen. If the payer never claims, or the amount is below the minimum that can be returned, refundLifecycleStatus does not reach completed.

Integrator handling guidance

Use these rules when mapping payment statuses to your internal order or invoice state.

processing

Treat as payment detected, but not complete.

A processing status means Bead has detected funds and the payment is underway. It does not mean the payment is paid.

Do not fulfill the order, release goods, grant digital access, ship an item, or mark an invoice as paid based only on processing.

For most tender types, processing may be short enough that the customer can remain in the payment flow until the outcome is returned.

For BTC Classic / Bitcoin on-chain payments, processing can last several minutes or longer. In those flows, the recommended customer experience is to acknowledge that the payment has been detected, let the customer move on, and use webhooks or this endpoint to confirm the outcome.

Recommended BTC Classic handling:

  • show the customer that the BTC payment has been detected

  • explain that Bitcoin on-chain confirmation can take several minutes

  • move the customer to an order, invoice, receipt, or status screen

  • keep the internal order or invoice in a pending payment state

  • use Payment Webhooks or this endpoint to detect the outcome

  • fulfill only after the payment reaches completed or overpaid

Example customer message:

completed

  • Treat as a paid payment.

  • Store the returned tenderType as the tender actually paid.

  • Proceed with fulfillment after you have confirmed the outcome via webhooks or this endpoint.

  • Use paymentId, statusCode, tenderType, reference, and receivedTime to support order lookup and customer support workflows.

overpaid

  • Treat as a paid payment and fulfill the order.

  • The requested amount settles to the merchant like a completed payment.

  • The excess is returned to the payer through Bead's reclaim process. Bead emails the payer reclaim instructions when an email is on file.

  • Do not ask the customer to pay again.

  • Expect later webhooks as the return of the excess progresses, with statusCode still overpaid and refundLifecycleStatus updated. Keep the order fulfilled.

underpaid

  • Treat as a declined payment. Nothing was processed for the order.

  • Do not fulfill the order.

  • Offer the customer a new payment, using your normal retry or tender selection flow. The original payment session cannot be topped up.

  • The amount sent is returned to the payer through Bead's reclaim process.

  • Expect later webhooks as the return progresses, with statusCode still underpaid and refundLifecycleStatus updated.

expired, abandoned, invalid, cancelled

  • Treat as not paid.

  • Do not fulfill the order.

  • If funds were sent (not applicable to abandoned), they remain unconverted and are handled through reclaim.

  • For abandoned, no funds were requested. If the customer still wants to pay, create a new payment.

For how these states behave in full flows, see the Payment Scenarios pages, which walk through overpaid, underpaid, and reclaim flows in more detail.

Reclaiming crypto

When a payment ends in one of the following states:

  • overpaid (the excess only)

  • underpaid

  • expired

  • invalid

  • cancelled

crypto associated with that payment is returned to the payer through Bead's reclaim process.

Email capture behavior

Bead uses an email based reclaim flow to return crypto.

  • if an email address is included in the original payment request, common in digital and virtual terminal flows, Bead will email instructions to the payer when reclaim is required

  • if an email address is not included in the request, common in physical or terminal based flows, the hosted payment page will prompt the customer to enter an email address when one of these outcomes occurs, then Bead emails the reclaim instructions

Your integration does not need to implement the reclaim process directly, but you should:

  • display clear messaging in your UI when these statuses occur

  • add internal flags or notes so support and finance teams can recognize reclaim scenarios

  • avoid automatically retrying or recreating payments without clear customer intention

  • create a new payment session when the customer is ready to attempt payment again after a not paid outcome

Error responses

Common error responses

Code
Condition

401

Missing or invalid API key. Confirm the X-Api-Key header is present and the key is valid for this environment.

403

Authenticated, but not permitted to view this payment in the current context. Confirm you are using the correct API key for the terminal and merchant relationship tied to this payment.

404

No payment exists for this paymentId, or it is not visible in the current context.

Log the response body and headers for debugging, but avoid exposing raw error text directly to end users.

Best practices

Recommended patterns when using the payment status endpoint:

Prefer webhooks for real time changes

Configure Payment Webhooks so your system receives status updates automatically, including reclaim progress and the automatic abandoned and expired closures. Use this endpoint for ad hoc checks and support workflows, not as your primary real time mechanism.

Webhooks are especially important for longer-running payment flows such as BTC Classic / Bitcoin on-chain. In those flows, the customer may leave the payment page after the payment reaches processing, while the merchant still needs to know the outcome.

Recommended pattern:

  • use the hosted payment page or status endpoint to show the customer the current payment state

  • use webhooks to update the merchant order, invoice, or fulfillment workflow

  • use this endpoint for customer support, reconciliation checks, or manual refresh actions

  • avoid relying on the customer keeping a browser tab open until the outcome is known

Use paymentId as the primary lookup key

Save the paymentId from the Create Payment response alongside your order or invoice. Use it to correlate status checks, webhooks, and Reporting records. trackingId is a legacy identifier that is deprecated but still supported for backwards compatibility; new integrations should use paymentId.

Store the actual paid tenderType

Save the returned tenderType once the payment has an outcome. This lets your system distinguish between the tenders offered during checkout and the tender actually used to pay.

For example, if a hosted payment flow allowed multiple tenders but the customer paid with Bitcoin Lightning, the completed payment status returns tenderType: "bitcoin_Lightning".

Map status codes to internal order states

Translate every status into an internal state that your business and support team understand. completed and overpaid are paid. underpaid, expired, abandoned, invalid, and cancelled are not paid. Track reclaim progress separately, using refundLifecycleStatus.

Use a pending state for BTC Classic processing

For BTC Classic / Bitcoin on-chain payments, map processing to an internal pending state such as:

  • payment detected

  • pending confirmation

  • awaiting BTC confirmation

  • payment processing

Do not map BTC Classic processing to paid, approved, fulfilled, or complete.

Recommended mapping:

Bead status
Outcome
Internal state
Fulfillment behavior

created

Pending

Awaiting payment

Do not fulfill yet

processing

Pending

Payment detected / pending confirmation

Do not fulfill yet

completed

Paid

Paid

Fulfillment may proceed

overpaid

Paid

Paid, excess returned to payer through reclaim

Fulfillment may proceed

underpaid

Not paid

Payment declined / retry with a new payment

Do not fulfill

expired

Not paid

Payment expired

Do not fulfill

abandoned

Not paid

Payment not started / closed

Do not fulfill

invalid

Not paid

Payment invalid / review required

Do not fulfill

cancelled

Not paid

Payment cancelled

Do not fulfill

Avoid tight polling loops

If you must poll, use reasonable intervals and a backoff strategy. For anything beyond small scale, move to webhooks together with Reporting and Settlement.

Combine with Reporting and Settlement for reconciliation

Use this endpoint for single payment checks. For daily reconciliation and accounting, rely on the Reporting payment history endpoints and the Settlement APIs to see payments, batches, and payment settlement lines together.

Next steps

Legacy authentication

Some existing Payments integrations authenticate using OAuth password grant and send an access token as:

New integrations should use the terminal API key method described above. If you are on the legacy model, see Authentication.

Last updated