Hex Pay Docs
API Reference

Retrieve a payment

Retrieves the full details of a payment by its unique identifier.

The response structure varies by status:

  • created — amount, currency and timer are present. paymentDetails is absent — the customer has not yet selected a payment method.
  • pending — paymentDetails is populated with the blockchain address and exact coin amount. The customer must send the transfer.
  • completed — paymentDetails includes transactionSignatures confirming the on-chain transfer.
  • expired — Elapsed TTL. Reachable from both created and pending. paymentDetails is present only if the payment had reached pending first.
  • cancelled — Canceled by the merchant. Reachable from both created and pending. paymentDetails is present only if the payment had reached pending.
GET
/v1/payments/{paymentId}
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).

Formatuuid

Response 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"
  }
}