Payment Status Response Examples

This page provides representative payment status payloads for common Bead payment outcomes.

The same status payload shape is used when you retrieve a payment status directly and when Bead sends a payment status webhook to your system.

Use these examples when mapping Bead payment outcomes to your internal order, invoice, or support states.

Status payload references

Use the tracking endpoint when you need to check the current status of a specific payment on demand.

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

Bead also sends payment status webhook events to the configured webhook URL for the terminal or payment. Your webhook handler should process the request body using the same status payload structure shown in the examples below.

POST {yourWebhookUrl}
Content-Type: application/json

Payload shape

The status payload includes identifiers, the current payment state, amount information, and optional merchant-supplied metadata.

{
  "paymentId": "string",
  "trackingId": "string",
  "paymentCode": "string",
  "statusCode": "created | processing | completed | underpaid | overpaid | expired | invalid | cancelled",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      },
      "inRequestedCurrency": {
        "amount": 0,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "string",
  "description": "string",
  "receivedTime": "2026-05-29T17:10:01Z",
  "terminalId": "string",
  "merchantId": "string",
  "errorMessage": null
}

Field notes

Field	Description
paymentId	Bead payment identifier. Use this value with GET /Payments/{id}/tracking.
trackingId	Tracking identifier returned when the payment was created. Store this with your internal order or invoice record for correlation.
paymentCode	Short payment code shown on the hosted payment page and in reporting.
statusCode	Current Bead payment status. Use this as the source of truth for payment state.
amounts.requested.inRequestedCurrency	Amount requested from the customer in the original requested currency.
amounts.requested.inPaymentCurrency	Amount expected in the selected payment currency, when available.
amounts.paid.inPaymentCurrency	Amount actually received in the payment currency.
reference	Optional merchant-supplied reference from the original payment request.
description	Optional merchant-supplied description from the original payment request.
receivedTime	Timestamp associated with the status event or update.
terminalId	Terminal associated with the payment.
merchantId	Merchant associated with the payment.
errorMessage	Additional error context when available. Usually null for normal lifecycle states.

Status examples covered

Status	What the example shows
created	Payment record created; no funds confirmed yet
processing	Payment is in progress; final outcome is not yet known
completed	Customer paid the requested amount
underpaid	Customer sent less than the requested amount
overpaid	Customer sent more than the requested amount
expired	Payment expired before completion
cancelled	Payment was cancelled before completion
invalid	Irregular or unsupported payment event requiring exception handling

Refund statuses are not shown on this page.

Created

A created payment has been created, but the customer has not completed payment and no funds have been confirmed.

{
  "paymentId": "pay_created_example",
  "trackingId": "trk_created_example",
  "paymentCode": "4DPJ2MEPAZHR",
  "statusCode": "created",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      },
      "inRequestedCurrency": {
        "amount": 1.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "abc123",
  "description": "test",
  "receivedTime": "2026-05-29T18:17:16Z",
  "terminalId": "term_created_example",
  "merchantId": "merch_created_example",
  "errorMessage": null
}

Processing

A processing payment is still in progress. The customer or wallet flow may have started, but the final payment outcome is not yet known.

Do not treat processing as a successful final state.

{
  "paymentId": "pay_processing_example",
  "trackingId": "trk_processing_example",
  "paymentCode": "6J2BNQBHEBHC",
  "statusCode": "processing",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 1.00,
        "currency": {
          "id": 101,
          "code": "CIT_USD_VENMO",
          "name": "Venmo",
          "symbol": "$"
        }
      },
      "inRequestedCurrency": {
        "amount": 1.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "abc123",
  "description": "test",
  "receivedTime": "2026-05-30T00:03:50Z",
  "terminalId": "term_processing_example",
  "merchantId": "merch_processing_example",
  "errorMessage": null
}

Completed

A completed payment indicates that the customer paid the requested amount.

{
  "paymentId": "pay_completed_example",
  "trackingId": "trk_completed_example",
  "paymentCode": "D8CU3N7A6CF4",
  "statusCode": "completed",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00000014,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 0.01,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00000014,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "POS-1780074506214",
  "description": "Leave a Penny",
  "receivedTime": "2026-05-29T17:10:01Z",
  "terminalId": "term_completed_example",
  "merchantId": "merch_completed_example",
  "errorMessage": null
}

Underpaid

An underpaid payment means the customer sent less than the requested amount.

The requested and paid objects show the difference between the amount expected and the amount actually received.

{
  "paymentId": "pay_underpaid_example",
  "trackingId": "trk_underpaid_example",
  "paymentCode": "KEYJWDJZR3TD",
  "statusCode": "underpaid",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00031198,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 25.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00031197,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "494810",
  "description": "Gift of College Payment for Transaction 494810",
  "receivedTime": "2026-05-08T23:50:45Z",
  "terminalId": "term_underpaid_example",
  "merchantId": "merch_underpaid_example",
  "errorMessage": null
}

Overpaid

An overpaid payment means the customer sent more than the requested amount.

The requested and paid objects show the difference between the amount expected and the amount actually received.

{
  "paymentId": "pay_overpaid_example",
  "trackingId": "trk_overpaid_example",
  "paymentCode": "EV5V2Z6V9TZH",
  "statusCode": "overpaid",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00000013655,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 0.01,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00000014,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "abc123",
  "description": "test",
  "receivedTime": "2026-04-10T19:14:13Z",
  "terminalId": "term_overpaid_example",
  "merchantId": "merch_overpaid_example",
  "errorMessage": null
}

Expired

An expired payment means the payment window expired before the payment completed.

{
  "paymentId": "pay_expired_example",
  "trackingId": "trk_expired_example",
  "paymentCode": "23DMFRZP52CY",
  "statusCode": "expired",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      },
      "inRequestedCurrency": {
        "amount": 0.01,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "POS-1778177453583",
  "description": "Leave a Penny",
  "receivedTime": "2026-05-31T18:15:05Z",
  "terminalId": "term_expired_example",
  "merchantId": "merch_expired_example",
  "errorMessage": null
}

Cancelled

A cancelled payment means the payment was cancelled before completion.

{
  "paymentId": "pay_cancelled_example",
  "trackingId": "trk_cancelled_example",
  "paymentCode": "X7KM9JBZCQND",
  "statusCode": "cancelled",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 100.00,
        "currency": {
          "id": 301,
          "code": "USDC_BASE",
          "name": "USDC Base",
          "symbol": "USDC"
        }
      },
      "inRequestedCurrency": {
        "amount": 100.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": {
          "id": 301,
          "code": "USDC_BASE",
          "name": "USDC Base",
          "symbol": "USDC"
        }
      }
    }
  },
  "reference": "6780e375-b9f8-41bf-9517-e275a7b75fd1",
  "description": "Area of Greatest Need",
  "receivedTime": "2026-05-29T17:24:07Z",
  "terminalId": "term_cancelled_example",
  "merchantId": "merch_cancelled_example",
  "errorMessage": null
}

Invalid

An invalid payment indicates an irregular or unsupported payment event. Examples may include multiple transactions, unsupported assets, compliance blocks, extreme market movement, or other exception conditions.

The exact errorMessage may vary by cause.

{
  "paymentId": "pay_invalid_example",
  "trackingId": "trk_invalid_example",
  "paymentCode": "INVALID12345",
  "statusCode": "invalid",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00025,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 20.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00025,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "ORDER-INVALID-EXAMPLE",
  "description": "Example invalid payment",
  "receivedTime": "2026-05-29T17:30:00Z",
  "terminalId": "term_invalid_example",
  "merchantId": "merch_invalid_example",
  "errorMessage": "Payment could not be completed because the payment event was invalid."
}

Implementation guidance

When mapping these payloads to your integration:

• Use statusCode as the primary state indicator.

• Store both paymentId and trackingId with your internal payment, invoice, or order record.

• Use paymentId when calling GET /Payments/{id}/tracking.

• Use trackingId to correlate Create Payment responses, webhook events, reporting records, and support workflows.

• Compare amounts.requested and amounts.paid when handling underpaid or overpaid.

• Treat processing as a non-final state.

• Treat completed as successful for the requested amount.

• Treat underpaid, overpaid, expired, invalid, and cancelled as not successful for fulfillment.

• Make webhook processing idempotent. You may receive the same event more than once.

• If a webhook event is missed, delayed, or received out of order, call GET /Payments/{id}/tracking to confirm the current state.

Related pages

• Payment Statuses

• Payment Webhooks

• Payment Scenarios

• Reclaiming Unconverted Crypto