Hex Pay Docs
API Reference

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

currencypaymentOptions.methodsInitial statuspaymentDetails
USD(omitted)createdabsent
TON(omitted)createdabsent
USD[{coin:"USDT",chain:"TON"}]pendingpopulated
TON[{coin:"USDT",chain:"TON"}]pendingpopulated
TON[{coin:"TON",chain:"TON"}]pendingpopulated
POST
/v1/payments
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

Header Parameters

X-Idempotency-Key?string

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.

Formatuuid
amountstring

The 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.

Match^(0\.\d*[1-9]\d*|[1-9]\d*(\.\d+)?)$
currencystring

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.

paymentOptions?PaymentOptions

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.

ttl?integer

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.

Default3600
Formatint64
Range900 <= value <= 43200
orderId?string

Merchant-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.

Lengthlength <= 128
description?string

Human-readable description of the payment purpose. May be displayed to the customer on the payment page.

Lengthlength <= 512
metadata?object

Arbitrary 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.

Propertiesproperties <= 10

Empty Object

webhookUrl?string

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.
Match^https://
Formaturi
Lengthlength <= 512
redirectUrl?string

HTTPS 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.

Match^https://
Formaturi
Lengthlength <= 512

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