Payment Statuses

Integrators can retrieve the current status of a payment at any time with the trackingId returned when the payment is created. Use this endpoint to verify completion, reconcile transactions, and keep internal records accurate.

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

Overview

Use the payment status endpoint when you want to:

• Retrieve real time payment status with a simple GET request

• Confirm final outcomes such as completed, expired, 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.

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. Funds remain unconverted and must be reclaimed by the customer.
overpaid	Customer sent more than requested. Requested amount converted, excess must be reclaimed.
expired	No funds received before the payment window expired. Any funds sent later must be reclaimed.
invalid	Irregular event such as multiple transactions, unsupported asset, compliance block, or extreme market movement. Funds 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.

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

the hosted payment page prompts the customer to enter an email address if it was not provided in the original request.

Bead emails instructions for reclaiming any unconverted funds associated with that payment. Your integration does not need to implement the reclaim process directly, but you may want to:

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