Payment Statuses

Integrators can easily retrieve the current status of a specific payment by using the trackingId returned during the payment creation process. This API allows you to verify transaction completion, handle reconciliation, and update your internal records accurately.

Overview

• Retrieve real-time payment statuses using a simple GET request.

• Confirm final transaction statuses like completed, expired, or invalid.

Requesting Payment Status

To retrieve payment status, issue a GET request to the following endpoint:

Request Example:

GET https://api.test.devs.beadpay.io/payments/{trackingId}/status
Authorization: Bearer YOUR_ACCESS_TOKEN
api-version: 0.2

Replace {trackingId} with the actual tracking ID returned when creating the payment.

Example Response

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

Status Codes

Integrators should implement logic based on the following status codes to properly handle payment outcomes in their applications:

Code	Status	Description
2	Completed	The customer sent the requested amount and processing was successful. Crypto is converted to the merchant's settlement currency and credited to their account.
3	Underpaid	The customer sent less than the requested amount. Funds are not converted and must be reclaimed by the customer. (See note below)
4	Overpaid	The customer sent more than the requested amount. The requested amount is converted and the payment is considered Completed. The overpaid amount is not converted and must be reclaimed by the customer. (See note below)
7	Expired	The customer's funds were not received before the payment window expired (varies by tender type). Funds will not be converted and must be reclaimed by the customer. (See note below)
8	Invalid	An irregular event occurred during processing, such as: detecting multiple transactions detecting a transaction for an incorrect or unsupported asset the customer's wallet was flagged for compliance reasons extreme market activity that will prevent the merchant from receiving the full payment amount Funds received are not converted and must be reclaimed by the customer. (See note below)
9	Cancelled	The customer or merchant requested to cancel the payment. If a transaction is detected, crypto will not be converted and may be reclaimed by the customer. (See note below)

Reclaiming Unconverted Crypto

For payment scenarios resulting in unconverted crypto, the customer provides their email address via the Hosted Payment Page (if one was not provided in the payment request) and will receive instructions from Bead detailing how they can reclaim their funds.

Next Steps

For real-time transaction updates, consider configuring Webhooks.

For integration questions, contact [e-mail].