Hex Pay Docs

Create Payment via API

Learn how to create cryptocurrency payments using the HexPay REST API

API Endpoint

POST https://api.hexpay.io/v1/payments

Optionally pass an X-Idempotency-Key header (UUID) to prevent duplicate payments on retry.

Two Modes of Payment Creation

The customer sees all payment methods enabled for your store and picks one at checkout. Use this when you want to give the customer flexibility.

The payment is created in created status. paymentDetails (deposit address and coin amount) is absent until the customer selects a method.

curl -X POST "https://api.hexpay.io/v1/payments" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -d '{
    "amount": "100.00",
    "currency": "USD",
    "orderId": "order-2026-00123",
    "webhookUrl": "https://merchant.com/webhooks/hexpay",
    "redirectUrl": "https://merchant.com/orders/order-2026-00123"
  }'
const response = await fetch("https://api.hexpay.io/v1/payments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...",
    "Content-Type": "application/json",
    "X-Idempotency-Key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  },
  body: JSON.stringify({
    amount: "100.00",
    currency: "USD",
    orderId: "order-2026-00123",
    webhookUrl: "https://merchant.com/webhooks/hexpay",
    redirectUrl: "https://merchant.com/orders/order-2026-00123"
  })
});

const payment = await response.json();
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  body := strings.NewReader(`{
    "amount": "100.00",
    "currency": "USD",
    "orderId": "order-2026-00123",
    "webhookUrl": "https://merchant.com/webhooks/hexpay",
    "redirectUrl": "https://merchant.com/orders/order-2026-00123"
  }`)

  req, _ := http.NewRequest("POST", "https://api.hexpay.io/v1/payments", body)
  req.Header.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("X-Idempotency-Key", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  respBody, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(respBody))
}
import requests

response = requests.post(
  "https://api.hexpay.io/v1/payments",
  json={
    "amount": "100.00",
    "currency": "USD",
    "orderId": "order-2026-00123",
    "webhookUrl": "https://merchant.com/webhooks/hexpay",
    "redirectUrl": "https://merchant.com/orders/order-2026-00123"
  },
  headers={
    "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...",
    "Content-Type": "application/json",
    "X-Idempotency-Key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }
)

payment = response.json()

Response — payment in created status:

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

Redirect the customer to checkoutUrl — they will see all available payment methods and pick one. paymentDetails appears once they select a method and the payment moves to pending.


2. Preselected Method

You specify the exact coin and chain upfront. The server resolves the deposit address immediately — the customer skips method selection and goes straight to the deposit screen.

The payment is created directly in pending status with paymentDetails already populated.

Use coin and chain symbol values from GET /v1/payment-methods. Values are case-sensitive.

curl -X POST "https://api.hexpay.io/v1/payments" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -d '{
    "amount": "100.00",
    "currency": "USD",
    "paymentOptions": {
      "methods": [{ "coin": "USDT", "chain": "TON" }]
    },
    "orderId": "order-2026-00124",
    "webhookUrl": "https://merchant.com/webhooks/hexpay"
  }'
const response = await fetch("https://api.hexpay.io/v1/payments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...",
    "Content-Type": "application/json",
    "X-Idempotency-Key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  },
  body: JSON.stringify({
    amount: "100.00",
    currency: "USD",
    paymentOptions: {
      methods: [{ coin: "USDT", chain: "TON" }]
    },
    orderId: "order-2026-00124",
    webhookUrl: "https://merchant.com/webhooks/hexpay"
  })
});

const payment = await response.json();
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  body := strings.NewReader(`{
    "amount": "100.00",
    "currency": "USD",
    "paymentOptions": {
      "methods": [{ "coin": "USDT", "chain": "TON" }]
    },
    "orderId": "order-2026-00124",
    "webhookUrl": "https://merchant.com/webhooks/hexpay"
  }`)

  req, _ := http.NewRequest("POST", "https://api.hexpay.io/v1/payments", body)
  req.Header.Add("Authorization", "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...")
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("X-Idempotency-Key", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  respBody, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(respBody))
}
import requests

response = requests.post(
  "https://api.hexpay.io/v1/payments",
  json={
    "amount": "100.00",
    "currency": "USD",
    "paymentOptions": {
      "methods": [{"coin": "USDT", "chain": "TON"}]
    },
    "orderId": "order-2026-00124",
    "webhookUrl": "https://merchant.com/webhooks/hexpay"
  },
  headers={
    "Authorization": "Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjFjZDZhOTIy...",
    "Content-Type": "application/json",
    "X-Idempotency-Key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }
)

payment = response.json()

Response — payment immediately in pending status with deposit address:

{
  "id": "019327c6-2058-7901-b234-56789abcdeff",
  "status": "pending",
  "orderId": "order-2026-00124",
  "amount": "100.00",
  "currency": "USD",
  "checkoutUrl": "https://payment.hexpay.io/019327c6-2058-7901-b234-56789abcdeff",
  "paymentDetails": {
    "address": "UQBf_DO8wsBddOcMnGEOyREEHPPKMBL2F26GQFOV7FQdYY_a",
    "coinAmount": "100.04",
    "coin": {
      "name": "Tether",
      "symbol": "USDT",
      "imgUrl": "https://assets.hexpay.io/coins/usdt.svg"
    },
    "chain": {
      "name": "TON",
      "symbol": "TON",
      "imgUrl": "https://assets.hexpay.io/chains/ton.svg"
    }
  },
  "timer": {
    "createdAt": "2026-01-20T10:00:00Z",
    "expiresAt": "2026-01-20T11:00:00Z"
  }
}

You can either redirect the customer to checkoutUrl (they land directly on the deposit screen) or display paymentDetails.address and paymentDetails.coinAmount in your own UI — they must send exactly that amount to that address on the TON blockchain.


Request Fields

FieldTypeRequiredDescription
amountstringYesPositive decimal greater than zero, e.g. "100.00". No leading zeros on the integer part.
currencystringYesFiat code (USD, EUR, RUB) or coin ticker (TON, USDT, NOT, DOGS, BUILD, BLUM, DUST, DYOR, STON, XAUt0). Defines the unit of value, not the payment coin.
paymentOptions.methodsarrayNoRestricts the methods offered to the customer. Currently exactly one {coin, chain} entry: HexPay preselects it for the customer (Preselected mode). Omit for Customer Choice.
ttlinteger (int64)NoPayment window in seconds. Min 900, max 43200, default 3600.
orderIdstringNoYour internal order ID, max 128 chars. Returned in all payment objects and in the webhook.
descriptionstringNoHuman-readable payment purpose, max 512 chars. May be shown to the customer.
metadataobjectNoArbitrary key-value pairs (max 10 keys, keys up to 64 chars, string values up to 512 chars). Returned in all payment objects and in the webhook.
webhookUrlstringNoHTTPS URL that receives a POST when the payment reaches completed. Must be publicly reachable from the internet; non-public addresses are rejected.
redirectUrlstringNoHTTPS URL of your page (e.g. the order page), max 512 chars. The checkout page links to it once the payment is completed, expired or cancelled. If omitted, the link leads to the HexPay site.
X-Idempotency-Keystring (UUID)NoHeader. If provided, retrying with the same key within 24 hours returns the stored response without creating a duplicate payment. Responses with status 401, 403, 404, 408, 409, 429, 500, 502, 503, 504 are not stored, so a retry runs again.

Field names are case-sensitive and use lowerCamelCase. Unknown fields, including old names such as order_id or webhookURL, are silently ignored.

Supported currency + method 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

Tracking Payment Status

After creating a payment, poll its status to know when to fulfill the order.

For lightweight polling use GET /v1/payments/{id}/status — it returns only the status field. Once the status you care about is reached, fetch the full object with GET /v1/payments/{id}.

created  →  pending  →  completed  ✓ fulfill order
       ↘           ↘
        cancelled   expired

Configure webhookUrl when creating the payment to receive a POST notification when the payment is completed — this removes the need to poll at all.

Learn about webhooks →


Returning the Customer to Your Store

Pass redirectUrl when creating the payment to bring the customer back to your site after checkout. Usually this is the order page.

When the payment reaches completed, expired or cancelled, the checkout page shows the result and a Go back to the store link to redirectUrl. HexPay does not redirect automatically: the customer follows the link. Without redirectUrl the link leads to the HexPay site.

Requirements:

  • An absolute HTTPS URL, up to 512 characters. Plain HTTP, relative URLs and other schemes (javascript:, data:) are rejected with 400 and code invalid_redirect_url.
  • The URL is used as is. HexPay does not append the payment ID or status, so put everything your page needs into the URL itself, e.g. https://merchant.com/orders/order-2026-00123.

Reaching redirectUrl does not prove the payment succeeded: the customer can open it at any time. Before fulfilling the order, check the status with GET /v1/payments/{id}/status or wait for the webhook.


Next Steps