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.

Overview

• Retrieve real-time payment status with a simple GET request.

• Confirm final outcomes such as completed, expired, or invalid.

Requesting payment status

GET https://api.test.devs.beadpay.io/payments/tracking/{trackingId}
Authorization: Bearer YOUR_ACCESS_TOKEN

Replace {trackingId} with the value returned by the Create Payment call.

Example response

{
  "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 marked (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; conversion/settlement in progress.
completed	Customer sent the requested amount; crypto (if any) converted and credited.
underpaid	Customer sent less than requested; funds 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; funds must be reclaimed.
invalid	Irregular event (multiple tx, unsupported asset, compliance block, extreme market movement); funds must be reclaimed.
cancelled	Customer or merchant cancelled; any funds remain unconverted and may be reclaimed.
fullyRefunded (reserved)	Will indicate that the entire payment has been refunded.
partiallyRefunded (reserved)	Will indicate a partial refund of the payment.

Reclaiming unconverted crypto

When a payment ends in underpaid, overpaid, expired, invalid, or cancelled, the customer is prompted on the hosted page to enter an email address (if not provided in the original request). Bead emails instructions for reclaiming any unconverted funds.

Next steps

• For real-time updates, configure Webhooks.

• For integration questions, email [email protected].