Payment Statuses

Integrators can retrieve the current status of a payment at any time using the trackingId 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, or invalid

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

Endpoint

GET /payments/tracking/{trackingId}

Path parameters

Name	Type	Required	Description
trackingId	string	Yes	Tracking identifier returned by the Create Payment response

Required headers (preferred)

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

Header	Value
X-Api-Key	{apiKey}
Accept	application/json

Notes:

• apiKey is the secret credential

• maskedApiKey is not usable

• Send the full apiKey value in the X-Api-Key header on every Payments request

Example request

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

Example response

The full response in your environment may include additional fields such as conversion details, settlement amounts, and metadata. Treat statusCode as the primary state indicator and use other fields as needed.

{
  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "statusCode": "completed",
  "amounts": {
    "requested": { "amount": 100.00, "currency": "USD" },
    "paid":      { "amount": 100.00, "currency": "USD" }
  },
  "reference": "ORDER123",
  "completedAt": "2025-03-04T10:20:30Z"
}

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

Status codes

Status code	Description
created	Payment record created, waiting for customer funds.
processing	Funds detected and conversion or settlement processing in progress.
completed	Customer sent the requested amount. Crypto, if any, has been converted and credited.
underpaid	Customer sent less than requested. The payment should be treated as not completed. Funds remain unconverted and will be returned to the payer through the reclaim process.
overpaid	Customer sent more than requested. The requested amount will be processed and settled. The overage 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.

Integrator handling guidance

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

completed

• Treat as successful payment.

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

underpaid

• Treat as not successful payment.

• Assume the transaction is not going through.

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

• Do not fulfill the order based on an underpaid status.

overpaid

• Treat as successful payment for the requested amount.

• Proceed with fulfillment once you have confirmed the final state, even though the customer sent more than requested.

• The customer does not need to take additional action to receive the overage back, other than completing the reclaim steps when prompted.

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.

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

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 apiKey for the terminal and merchant relationship tied to this payment.
404	No payment exists for this trackingId, 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.

• Store and use trackingId as the lookup key Save the trackingId from the Create Payment response alongside your order or invoice. Use it to correlate status checks, webhooks, and Reporting records.

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

• 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 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 (supported for existing integrators)

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

Authorization: Bearer {access_token}

New Payments integrations should use the terminal API key method described above. If you are on the legacy model, see Authentication for token endpoint details and refresh token usage.