API Reference
Retrieve a payment
Retrieves the full details of a payment by its unique identifier.
The response structure varies by status:
created—amount,currencyand timer are present.paymentDetailsis absent — the customer has not yet selected a payment method.pending—paymentDetailsis populated with the blockchain address and exact coin amount. The customer must send the transfer.completed—paymentDetailsincludestransactionSignaturesconfirming the on-chain transfer.expired— Elapsed TTL. Reachable from bothcreatedandpending.paymentDetailsis present only if the payment had reachedpendingfirst.cancelled— Canceled by the merchant. Reachable from bothcreatedandpending.paymentDetailsis present only if the payment had reachedpending.
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"Payment created; customer has not yet selected a payment method.
{
"id": "019327c6-2058-7901-b234-56789abcdeff",
"status": "created",
"orderId": "order-2026-00123",
"amount": "100.00",
"currency": "USD",
"checkoutUrl": "https://payment.hexpay.io/019327c6-2058-7901-b234-56789abcdeff",
"metadata": {
"customer_id": "cust_abc123"
},
"timer": {
"createdAt": "2026-01-20T10:00:00Z",
"expiresAt": "2026-01-20T11:00:00Z"
}
}{
"error": {
"type": "invalid_request_error",
"message": "paymentId must be a valid UUID",
"code": "invalid_payment_id",
"param": "paymentId"
}
}{
"error": {
"type": "authentication_error",
"message": "Missing authorization token",
"code": "auth_missing"
}
}{
"error": {
"type": "not_found_error",
"message": "Payment not found",
"code": "payment_not_found"
}
}{
"error": {
"type": "api_error",
"message": "Internal server error",
"code": "internal_error"
}
}