Create a payment
Creates a new payment for your store and returns the full payment object.
Denomination
Specify the value the customer owes via the top-level amount (decimal string)
and currency (fiat code or coin ticker) fields.
Preselected
Pass paymentOptions.methods with exactly one entry containing both coin
and chain. HexPay selects this method on behalf of the customer, resolves the
address immediately and returns the payment in pending status with
paymentDetails populated. The customer proceeds straight to the deposit screen
without any method selection step.
Customer Choice
Omit paymentOptions. All store-enabled payment methods are offered to the customer
at checkout. The payment starts in created status.
Supported combinations
currency | paymentOptions.methods | Initial status | paymentDetails |
|---|---|---|---|
USD | (omitted) | created | absent |
TON | (omitted) | created | absent |
USD | [{coin:"USDT",chain:"TON"}] | pending | populated |
TON | [{coin:"USDT",chain:"TON"}] | pending | populated |
TON | [{coin:"TON",chain:"TON"}] | pending | populated |
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
Header Parameters
Optional UUID key for idempotent request processing. If the server receives two requests with the same key within a 24-hour window, the second returns the stored response from the first without creating a duplicate resource. Responses with status 401, 403, 404, 408, 409, 429, 500, 502, 503 or 504 are not stored. Generate a fresh key for each logically distinct operation.
uuidThe payment value as a positive decimal string. Zero is not allowed.
No leading zeros are permitted on the integer part ("007" is invalid; use "7").
For fiat currencies up to 2 decimal places are recommended.
For crypto tickers precision depends on the coin.
^(0\.\d*[1-9]\d*|[1-9]\d*(\.\d+)?)$Ticker symbol for the denomination. Accepts fiat codes (USD, EUR, RUB)
or TON-ecosystem coin tickers (TON, USDT, NOT, DOGS, BUILD, BLUM,
DUST, DYOR, STON, XAUt0).
This field defines the unit of value — it does not determine the coin
the customer pays with. Payment coin is controlled by paymentOptions.methods.
Any supported ticker is accepted, regardless of which payment methods are enabled for your store.
Optional restriction on which payment methods are offered at checkout.
When omitted entirely, all payment methods enabled for your store are shown
and the payment is created in created status.
Time-to-live in seconds. Defines how long the payment remains active
from the moment of creation. Once the TTL elapses the payment moves to
expired status — this can happen from either created or pending.
Minimum: 900 (15 minutes). Maximum: 43200 (12 hours).
Defaults to 3600 (1 hour) if not specified.
3600int64900 <= value <= 43200Merchant-defined external order identifier. Use this to correlate a HexPay payment with your internal order or invoice system. Returned on all payment objects and included in the webhook payload.
length <= 128Human-readable description of the payment purpose. May be displayed to the customer on the payment page.
length <= 512Arbitrary key-value pairs for merchant use. All values must be strings. Returned on all payment objects and included in the webhook payload. Maximum 10 keys; key names up to 64 characters, values up to 512 characters. Keys are stored as provided and are not renamed.
properties <= 10Empty Object
HTTPS URL to which HexPay will POST a webhook notification when this
payment reaches completed status. No webhooks are sent for other statuses.
Requirements:
- Must use HTTPS. Plain HTTP URLs are rejected.
- Must be publicly reachable from the internet. Non-public addresses are rejected, and host names that resolve to them are blocked at delivery time.
- Make sure your server is configured to accept POST requests at this URL before creating payments.
^https://urilength <= 512HTTPS URL of your page (e.g. the order page) that the checkout page links to
once the payment is finished (completed, expired or cancelled), so the
customer can return to your store.
Requirements:
- Must be an absolute HTTPS URL. Plain HTTP and other schemes are rejected.
- Maximum 512 characters.
If omitted, the checkout page uses the default HexPay URL.
^https://urilength <= 512Response Body
curl -X POST "https://api.hexpay.io/v1/payments" \ -H "X-Idempotency-Key: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \ -H "Content-Type: application/json" \ -d '{ "amount": "100.00", "currency": "USD", "orderId": "order-2026-00123", "webhookUrl": "https://merchant.com/webhooks/hexpay" }'{
"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",
"timer": {
"createdAt": "2026-01-20T10:00:00Z",
"expiresAt": "2026-01-20T11:00:00Z"
}
}{
"error": {
"type": "invalid_request_error",
"message": "Request body is not valid JSON",
"code": "invalid_request"
}
}{
"error": {
"type": "authentication_error",
"message": "Missing authorization token",
"code": "auth_missing"
}
}{
"error": {
"type": "not_found_error",
"message": "Payment method not found",
"code": "payment_method_not_found"
}
}{
"error": {
"type": "rate_limit_error",
"message": "Payment concurrent limit exceeded",
"code": "payment_concurrent_limit_exceeded"
}
}{
"error": {
"type": "api_error",
"message": "Internal server error",
"code": "internal_error"
}
}