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.

Overview

Use the payment status endpoint when you want to:

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

• confirm final outcomes such as completed, expired, underpaid, overpaid, or invalid

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

GET /Payments/{paymentId}/tracking
X-Api-Key: {apiKey}
Accept: application/json

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:

GET /Payments/{paymentId}/tracking
Authorization: Bearer {access_token}
Accept: application/json

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

Example request

curl "https://api.test.devs.beadpay.io/Payments/{paymentId}/tracking" \
-H "X-Api-Key: {apiKey}" \
-H "Accept: application/json"

Example response

The endpoint returns a Payment object. The full response in your environment may include additional fields such as payment instructions, conversion details, transactions, notifications, settlement status, and metadata.

The example below is abbreviated to highlight the fields most commonly used for status handling. For completed payments, tenderType identifies the tender actually used to pay. The response uses created and updated; it does not include a completedAt field.

{
  "id": "65f0b274f9a4c9a3f8d4b2a1",
  "terminalId": "65f0b274f9a4c9a3f8d4b2a1",
  "paymentCode": "PAY-9X7K2M",
  "paymentId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "statusCode": "completed",
  "tenderType": "bitcoin_Lightning",
  "reqCurrencyId": 1,
  "payCurrencyId": 3,
  "amounts": {
    "requested": {
      "inRequestedCurrency": {
        "amount": 100.00,
        "amountPrecision": 2,
        "currencyId": 1
      },
      "inPaymentCurrency": {
        "amount": 0.00154321,
        "amountPrecision": 8,
        "currencyId": 3
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00154321,
        "amountPrecision": 8,
        "currencyId": 3
      }
    },
    "settleableAmount": {
      "amount": 100.00,
      "amountPrecision": 2,
      "currencyId": 1
    },
    "partnerFees": []
  },
  "reference": "ORDER123",
  "created": "2025-03-04T10:15:30Z",
  "updated": "2025-03-04T10:20:30Z"
}

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:

{
  "statusCode": "completed",
  "tenderType": "bitcoin_Lightning"
}

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 completed 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, not processing, as the fulfillment trigger

Status values

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

Statuses marked as reserved are not currently returned by the API but are documented for future compatibility.

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:

• underpaid when less than the requested amount is sent

• overpaid when more than the requested amount is sent

For both underpaid and overpaid, the payment is not treated as successful. The crypto that was paid remains unconverted and is returned to the payer through Bead's reclaim process.

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 it is not final. 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. Treat this as the successful final payment state and the fulfillment trigger.
underpaid	Customer sent less than requested. The payment should be treated as not completed. The crypto that was paid remains unconverted and will be returned to the payer through the reclaim process.
overpaid	Customer sent more than requested. The payment should be treated as not completed. The crypto that was paid remains unconverted and will be returned to the payer through the reclaim process.
expired	No funds received before the payment window expired. Any funds sent later remain unconverted and must be reclaimed.
invalid	Irregular event such as multiple transactions, unsupported asset, compliance block, or extreme market movement. Funds remain unconverted and must be reclaimed.
cancelled	Customer or merchant cancelled the payment. Any funds remain unconverted and may be reclaimed.
fullyRefunded	Reserved. Will indicate that the entire payment has been refunded.
partiallyRefunded	Reserved. Will indicate that a portion of the payment has been refunded.

Status finality

Bead payment statuses fall into two categories: stateful and final.

Stateful statuses are transitional. A payment in a stateful status may advance to a new status, and your webhook consumer should expect to receive additional events as the payment progresses.

• created — payment is open, waiting for the customer to initiate funds

• processing — funds detected; conversion or settlement is underway

Final statuses are terminal. Once a payment reaches a final status, it will not transition again. No corrective, superseding, or follow-on webhook will be sent for that paymentId. Treat the first final-status event as the authoritative outcome.

• completed

• underpaid

• overpaid

• expired

• invalid

• cancelled

Design your webhook consumer to handle multiple events per paymentId during the stateful phase, and to treat the first final status as the definitive result. A completed webhook will never be followed by a cancelled webhook for the same payment, and a cancelled webhook will never be revised to 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 has reached its successful final state.

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 final status 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 when the payment reaches completed.

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 final status

• fulfill only after the payment reaches completed

Example customer message:

Your BTC payment has been detected and is now processing.

Bitcoin on-chain payments can take several minutes to confirm. You do not need to keep this page open. The merchant will confirm when the payment is complete.

completed

• Treat as successful payment.

• Store the returned tenderType as the tender actually paid.

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

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

underpaid

• Treat as not successful payment.

• The transaction is not going through. Do not fulfill the order based on an underpaid status.

• The crypto that was paid remains unconverted and will be returned to the payer through Bead's reclaim process.

• Prompt the customer to attempt payment again with a new hosted payment session, based on your normal retry or tender selection flow.

overpaid

• Treat as not successful payment.

• The transaction is not going through. Do not fulfill the order based on an overpaid status.

• The requested amount is not processed as a successful payment, and the overage is not split out separately. The crypto that was paid remains unconverted and will be returned to the payer through Bead's reclaim process.

• Prompt the customer to attempt payment again with a new hosted payment session, based on your normal retry or tender selection flow.

expired, invalid, cancelled

• Treat as not successful payment.

• Do not fulfill the order.

• If funds were sent, they remain unconverted and are handled through reclaim.

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

Reclaiming unconverted crypto

When a payment ends in one of the following states:

• underpaid

• overpaid

• expired

• invalid

• cancelled

any unconverted crypto associated with that payment is handled through Bead's reclaim process.

For underpaid and overpaid, the full crypto amount paid by the customer is returned through reclaim. The payment should not be treated as successful, and the integrator should not fulfill the order based on either status.

Email capture behavior

Bead uses an email based reclaim flow to return unconverted 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

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. 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 when the payment reaches completed.

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 final completion

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 after the payment reaches a final state. 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 completed, underpaid, overpaid, expired, invalid, and cancelled into internal states that your business and support team understand.

Only completed should be treated as a successful payment. Statuses such as underpaid and overpaid should be treated as not successful and routed through the appropriate retry and reclaim messaging.

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	Stateful or final	Internal state	Fulfillment behavior
created	Stateful	Awaiting payment	Do not fulfill
processing	Stateful	Payment detected / pending confirmation	Do not fulfill
completed	Final	Paid	Fulfillment may proceed
underpaid	Final	Payment failed / reclaim required	Do not fulfill
overpaid	Final	Payment failed / reclaim required	Do not fulfill
expired	Final	Payment expired	Do not fulfill
invalid	Final	Payment invalid / review required	Do not fulfill
cancelled	Final	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

• Configure Payment Webhooks for real time payment events.

• Review Tender Types for the list of valid tenderType values.

• Review Why do BTC (on-chain) payments take longer? for more detail on Bitcoin on-chain confirmation timing and customer messaging.

• Review Choosing Tender Types by Payment Environment for guidance on when BTC Classic is appropriate for physical, digital, invoice, and delayed-fulfillment flows.

• Review Payment Scenarios for practical examples of handling non-happy-path statuses such as underpaid and overpaid.

• Use Reporting and Settlement to build dashboards and reconciliation jobs that operate over many payments at once.

Legacy authentication

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

Authorization: Bearer {access_token}

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