API Reference
Retrieve payment status
Returns only the current status of a payment — nothing else.
Use this endpoint for high-frequency polling when you only need to detect status transitions. It is significantly lighter than GET /v1/payments/{paymentID} because it skips address, amounts, and timer data.
Once you detect the status you care about (e.g. pending or completed), fetch the full object with GET /v1/payments/{paymentID} to get the deposit address or transaction signatures.
Possible status values
| Status | Meaning |
|---|---|
created | Awaiting method selection by the customer. |
pending | Deposit address assigned; awaiting on-chain transfer. |
completed | Transfer confirmed on-chain. Order can be fulfilled. |
expired | Payment window closed without a confirmed transfer. |
cancelled | Canceled by the merchant. |
AuthorizationBearer <token>
JWT token signed with the EdDSA algorithm. Obtain the token from the HexPay
merchant dashboard and pass it via the Authorization: Bearer <token> header.
In: header
Path Parameters
paymentIDstring
Unique identifier of the payment (UUID).
Format
uuidResponse Body
curl -X GET "https://api.hexpay.io/v1/payments/019327c6-2058-7901-b234-56789abcdeff/status"{
"status": "created"
}{
"error": {
"type": "invalid_request_error",
"message": "paymentID must be a valid UUID",
"code": "invalid_payment_id",
"param": "paymentID"
}
}{
"error": {
"type": "authentication_error",
"message": "Invalid or expired authentication token",
"code": "auth_invalid"
}
}{
"error": {
"type": "not_found_error",
"message": "No payment found with the specified ID",
"code": "payment_not_found"
}
}{
"error": {
"type": "api_error",
"message": "An unexpected error occurred. Please retry the request or contact support.",
"code": "internal_error"
}
}