Payments API

Create payment POST /v1/payments

• amount is a decimal string in token units (e.g. USDT with 6 decimals)—never use JavaScript Number.
• Encode the response address (Base58) in your QR code; show amount and token on your checkout UI.
• Duplicate orderNo for the same merchant returns 409; validation errors return 400.

Request

POST {baseUrl}/v1/payments
Content-Type: application/json
Authorization: Influx-HMAC-SHA256 ApiKey=<ApiKey>,Timestamp=<unix>,Signature=<hex>

{
  "orderNo": "ORDER-20260428-0001",
  "tokenSymbol": "USDT",
  "amount": "10.50",
  "expireSec": 1800,
  "notifyUrl": "https://merchant.example.com/webhook",
  "metadata": { "userId": "u_123" }
}

Field	Required	Description
orderNo	Yes	Unique merchant order reference
tokenSymbol	Yes	Must be enabled in your environment (often USDT)
amount	Yes	Token-denominated amount string
expireSec	Yes	Positive integer, order TTL in seconds
notifyUrl	Yes	HTTPS endpoint for payment.paid
metadata	No	Arbitrary JSON stored but not returned in API responses

Response 200

{
  "paymentId": "p_01HXXX...",
  "address": "TXxxxxxxxx...",
  "amount": "10.50",
  "amountRaw": "10500000",
  "tokenContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "tokenSymbol": "USDT",
  "paymentNetwork": "TRC20",
  "expireAt": "2026-04-28T17:00:00.000Z",
  "status": "PENDING"
}

Field	Description
paymentId	System payment ID for queries and webhooks
address	Deposit address (Base58)
amount / amountRaw	Payable amount (decimal string / smallest-unit integer string)
paymentNetwork	Chain family (often TRC20 at launch; more networks planned)
status	Initially PENDING

Errors

{ "error": "BAD_REQUEST", "message": "Invalid amount" }

{ "error": "UNAUTHORIZED", "message": "Invalid merchant HMAC signature" }

{ "error": "CONFLICT", "message": "Payment order already exists" }

---

Query payment GET /v1/payments/:paymentId

paymentId is the ID returned when the payment was created.

status: PENDING, PARTIAL, PAID, EXPIRED, CANCELED.

paidAmount, paidTxId, blockNum, and paidAt are non-null only after settlement-related states; confirmations is 0 before a transfer is recorded.

Request

GET {baseUrl}/v1/payments/p_01HXXX
Authorization: Influx-HMAC-SHA256 ApiKey=<ApiKey>,Timestamp=<unix>,Signature=<hex>

Response 200 (pending)

{
  "paymentId": "p_01HXXX...",
  "orderNo": "ORDER-20260428-0001",
  "status": "PENDING",
  "address": "TXxxxxxxxx...",
  "amount": "10.50",
  "amountRaw": "10500000",
  "tokenContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "tokenSymbol": "USDT",
  "paymentNetwork": "TRC20",
  "expireAt": "2026-04-28T17:00:00.000Z",
  "paidAmount": null,
  "paidTxId": null,
  "blockNum": null,
  "confirmations": 0,
  "paidAt": null
}

Response 200 (paid)

{
  "paymentId": "p_01HXXX...",
  "orderNo": "ORDER-20260428-0001",
  "status": "PAID",
  "address": "TXxxxxxxxx...",
  "amount": "10.50",
  "amountRaw": "10500000",
  "tokenContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "tokenSymbol": "USDT",
  "paymentNetwork": "TRC20",
  "expireAt": "2026-04-28T17:00:00.000Z",
  "paidAmount": "10.50",
  "paidTxId": "abc123def456...",
  "blockNum": "62000000",
  "confirmations": 22,
  "paidAt": "2026-04-28T16:32:10.000Z"
}

Errors

{ "error": "NOT_FOUND", "message": "Payment not found" }