Create Payment via API
Learn how to create cryptocurrency payments using the HexPay REST API
Before creating payments via API, make sure you have:
API Endpoint
POST https://api.hexpay.io/v1/paymentsOptionally pass an X-Idempotency-Key header (UUID) to prevent duplicate payments on retry.
Two Modes of Payment Creation
1. Customer Choice (Recommended)
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
| Field | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | Positive decimal greater than zero, e.g. "100.00". No leading zeros on the integer part. |
currency | string | Yes | Fiat 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.methods | array | No | Restricts the methods offered to the customer. Currently exactly one {coin, chain} entry: HexPay preselects it for the customer (Preselected mode). Omit for Customer Choice. |
ttl | integer (int64) | No | Payment window in seconds. Min 900, max 43200, default 3600. |
orderId | string | No | Your internal order ID, max 128 chars. Returned in all payment objects and in the webhook. |
description | string | No | Human-readable payment purpose, max 512 chars. May be shown to the customer. |
metadata | object | No | Arbitrary 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. |
webhookUrl | string | No | HTTPS URL that receives a POST when the payment reaches completed. Must be publicly reachable from the internet; non-public addresses are rejected. |
redirectUrl | string | No | HTTPS 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-Key | string (UUID) | No | Header. 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
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 |
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 expiredConfigure webhookUrl when creating the payment to receive a POST notification when the payment is completed — this removes the need to poll at all.
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 with400and codeinvalid_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.