API 参考

HTP 开放支付 API（签名接口）。两个环境共用一个地址，由 API Key 决定是沙箱还是生产。

下载 OpenAPI (YAML)Quickstart

接口地址

Environments

ok_test_… → SANDBOX · ok_live_… → PRODUCTION

鉴权

每个请求使用 HMAC-SHA256 签名，详见「请求签名」。

请求头: X-Key-Id、X-Timestamp、X-Nonce、X-Signature, Idempotency-Key

鉴权 →签名生成器 →

METHOD + "\n" +
PATH (with query) + "\n" +
X-Timestamp + "\n" +
X-Nonce + "\n" +
Idempotency-Key (or empty) + "\n" +
hex(sha256(body))

X-Signature = base64(HMAC-SHA256(api_secret, string_to_sign))

收款

通过 HTP App 收银台向 HTP 用户收取 USDT。

创建收款单

POST/open/v1/payments

创建状态为 CREATED 的收款单，返回 checkout_url，用户需在 HTP App 内打开并输入支付 PIN 确认。

out_order_no 是你的订单号，在同一 App、环境和订单类型下唯一。
超过 expire_minutes（默认由平台设置，一般 30 分钟）未支付即过期，查询时状态为 CLOSED。
设置 payer_sub 可指定唯一付款人；不设置则任意符合条件的 HTP 用户打开链接都可付款，支付后填入 user_sub。
手续费按审核通过的费率计算；net_amount = amount - fee_amount 为你实际入账金额。

不要依据浏览器跳转判断支付成功，请以 payment.paid 回调或查询订单为准。

请求头

X-Key-Idstring必填

签名请求头，见「请求签名」。

X-Timestampstring必填

签名请求头，见「请求签名」。

X-Noncestring必填

签名请求头，见「请求签名」。

X-Signaturestring必填

签名请求头，见「请求签名」。

Idempotency-Keystring必填

8–64 位 [A-Za-z0-9_-]。相同 Key + 相同请求体会重放首次成功的响应；相同 Key + 不同请求体返回 IDEMPOTENCY_KEY_REUSED。每个业务操作生成一个，重试时复用。

请求体 application/json

out_order_nostring必填

你的订单号，在同一 App、环境和订单类型下唯一。

amountstring必填

USDT 金额，正数，最多两位小数。

currencystring必填

USDT

descriptionstring

在 HTP 收银台展示给用户。

payer_substring

可选。唯一允许付款的用户的 OIDC sub。该用户须登录过你的 App 且未取消授权（否则 USER_NOT_AUTHORIZED）。

expire_minutesinteger

收银台有效期（分钟），默认为平台设置（30）。

响应

200 · Order

错误码

400INVALID_REQUEST — a field failed validation; message says which. Also returned when Idempotency-Key is missing or malformed.
401SIGNATURE_INVALID — missing headers, unknown or revoked key, wrong signature, timestamp outside the window, or a reused nonce.
403APP_UNAVAILABLE, PAYMENT_NOT_ENABLED, SANDBOX_USER_ONLY
409ORDER_ALREADY_EXISTS, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS
422INVALID_AMOUNT, CURRENCY_NOT_SUPPORTED, LIMIT_EXCEEDED, USER_NOT_AUTHORIZED, SELF_PAYMENT_FORBIDDEN
429TOO_MANY_REQUESTS — rate limit per app (default 600 requests/minute). Honour Retry-After.

# Sign first — see /docs/authentication or /tools/signature
curl -X POST '/open/v1/payments' \
  -H 'X-Key-Id: $HTP_KEY_ID' \
  -H 'X-Timestamp: $TS' \
  -H 'X-Nonce: $NONCE' \
  -H 'X-Signature: $SIGNATURE' \
  -H 'Idempotency-Key: $IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"out_order_no":"A20261107-0001","amount":"40.00","currency":"USDT","description":"Premium membership, 1 month","payer_sub":"2f6c0d1e8a9b4c7d","expire_minutes":30}'

{
  "trace_id": "6c1f0b9a3e2d4f5a",
  "status_code": 200,
  "message": "success",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "A20261107-0001",
    "order_type": "PAYMENT",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "0.00",
    "fee_amount": "0.40",
    "net_amount": "39.60",
    "currency": "USDT",
    "description": "Premium membership, 1 month",
    "user_sub": "2f6c0d1e8a9b4c7d",
    "checkout_url": "https://app.htp.example/open/checkout?token=Q2hlY2tvdXQ...",
    "expires_at": "2026-11-07T09:30:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

为此请求签名

关闭未支付的收款单

POST/open/v1/payments/{id}/close

关闭仍为 CREATED 的收款单，之后无法再支付。关闭已关闭的订单直接返回；已支付（PAID）的不能关闭（INVALID_STATE），请改用退款。无请求体，不需要 Idempotency-Key。

请求头

X-Key-Idstring必填

签名请求头，见「请求签名」。

X-Timestampstring必填

签名请求头，见「请求签名」。

X-Noncestring必填

签名请求头，见「请求签名」。

X-Signaturestring必填

签名请求头，见「请求签名」。

路径参数

idstring · uuid必填

创建订单时返回的 HTP 订单 id（UUID）。

响应

200 · Order

错误码

401SIGNATURE_INVALID — missing headers, unknown or revoked key, wrong signature, timestamp outside the window, or a reused nonce.
404ORDER_NOT_FOUND — no such order for this app in the key's environment.
409INVALID_STATE — only unpaid payments can be closed.
429TOO_MANY_REQUESTS — rate limit per app (default 600 requests/minute). Honour Retry-After.

# Sign first — see /docs/authentication or /tools/signature
curl -X POST '/open/v1/payments/0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d/close' \
  -H 'X-Key-Id: $HTP_KEY_ID' \
  -H 'X-Timestamp: $TS' \
  -H 'X-Nonce: $NONCE' \
  -H 'X-Signature: $SIGNATURE'

{
  "trace_id": "string",
  "status_code": 200,
  "message": "success",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "string",
    "order_type": "PAYMENT",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "40.00",
    "fee_amount": "40.00",
    "net_amount": "40.00",
    "currency": "USDT",
    "description": "string",
    "user_sub": "string",
    "checkout_url": "https://…",
    "expires_at": "2026-11-07T09:00:00Z",
    "completed_at": "2026-11-07T09:00:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

为此请求签名

退款

将已支付的收款单全额或部分退回付款人。

退款

POST/open/v1/payments/{id}/refunds

对 PAID 收款单全额或部分退款，同步完成（状态 SUCCEEDED）：从你的钱包扣除退款金额并退回原付款人。手续费不退。 可多次部分退款，直到 refunded_amount 等于 amount。

同时发送 payment.refunded 回调，data 为退款单，parent_id 为原收款单。

请求头

X-Key-Idstring必填

签名请求头，见「请求签名」。

X-Timestampstring必填

签名请求头，见「请求签名」。

X-Noncestring必填

签名请求头，见「请求签名」。

X-Signaturestring必填

签名请求头，见「请求签名」。

Idempotency-Keystring必填

路径参数

idstring · uuid必填

创建订单时返回的 HTP 订单 id（UUID）。

请求体 application/json

out_refund_nostring必填

你的退款单号，在同一 App 和环境下唯一。

amountstring必填

退款金额，不超过 amount - refunded_amount。

reasonstring

退款原因。

响应

200 · Order

错误码

400INVALID_REQUEST — a field failed validation; message says which. Also returned when Idempotency-Key is missing or malformed.
401SIGNATURE_INVALID — missing headers, unknown or revoked key, wrong signature, timestamp outside the window, or a reused nonce.
403APP_UNAVAILABLE, DEVELOPER_WALLET_UNAVAILABLE
404ORDER_NOT_FOUND — no such order for this app in the key's environment.
409REFUND_NOT_ALLOWED (payment not PAID), ORDER_ALREADY_EXISTS, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS
422INVALID_AMOUNT, REFUND_AMOUNT_EXCEEDED, INSUFFICIENT_BALANCE
429TOO_MANY_REQUESTS — rate limit per app (default 600 requests/minute). Honour Retry-After.

# Sign first — see /docs/authentication or /tools/signature
curl -X POST '/open/v1/payments/0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d/refunds' \
  -H 'X-Key-Id: $HTP_KEY_ID' \
  -H 'X-Timestamp: $TS' \
  -H 'X-Nonce: $NONCE' \
  -H 'X-Signature: $SIGNATURE' \
  -H 'Idempotency-Key: $IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"out_refund_no":"R20261107-0001","amount":"15.00","reason":"Customer cancelled"}'

{
  "trace_id": "7d2a1c0b9e8f4a3b",
  "status_code": 200,
  "message": "success",
  "data": {
    "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
    "out_order_no": "R20261107-0001",
    "order_type": "REFUND",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "SUCCEEDED",
    "amount": "15.00",
    "refunded_amount": "0.00",
    "fee_amount": "0.00",
    "net_amount": "15.00",
    "currency": "USDT",
    "description": "Customer cancelled",
    "user_sub": "2f6c0d1e8a9b4c7d",
    "completed_at": "2026-11-07T10:00:00Z",
    "created_at": "2026-11-07T10:00:00Z"
  }
}

为此请求签名

付款

从开发者钱包向 HTP 用户付款。

向用户付款

POST/open/v1/payouts

从你的钱包向 payee_sub 对应的用户付款，同步完成（状态 SUCCEEDED）并发送 payout.completed 回调。需审核开通付款功能（否则 PAYOUT_NOT_ALLOWED），付款限额与收款分开累计。

请求头

X-Key-Idstring必填

签名请求头，见「请求签名」。

X-Timestampstring必填

签名请求头，见「请求签名」。

X-Noncestring必填

签名请求头，见「请求签名」。

X-Signaturestring必填

签名请求头，见「请求签名」。

Idempotency-Keystring必填

请求体 application/json

out_order_nostring必填

你的付款单号。

amountstring必填

USDT 金额，最多两位小数。

currencystring必填

USDT

payee_substring必填

收款用户的 OIDC sub。

descriptionstring

展示给用户的说明。

响应

200 · Order

错误码

400INVALID_REQUEST — a field failed validation; message says which. Also returned when Idempotency-Key is missing or malformed.
401SIGNATURE_INVALID — missing headers, unknown or revoked key, wrong signature, timestamp outside the window, or a reused nonce.
403APP_UNAVAILABLE, PAYMENT_NOT_ENABLED, PAYOUT_NOT_ALLOWED, SANDBOX_USER_ONLY, DEVELOPER_WALLET_UNAVAILABLE
409ORDER_ALREADY_EXISTS, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_IN_PROGRESS
422INVALID_AMOUNT, CURRENCY_NOT_SUPPORTED, LIMIT_EXCEEDED, USER_NOT_AUTHORIZED, SELF_PAYMENT_FORBIDDEN, INSUFFICIENT_BALANCE
429TOO_MANY_REQUESTS — rate limit per app (default 600 requests/minute). Honour Retry-After.

# Sign first — see /docs/authentication or /tools/signature
curl -X POST '/open/v1/payouts' \
  -H 'X-Key-Id: $HTP_KEY_ID' \
  -H 'X-Timestamp: $TS' \
  -H 'X-Nonce: $NONCE' \
  -H 'X-Signature: $SIGNATURE' \
  -H 'Idempotency-Key: $IDEMPOTENCY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"out_order_no":"P20261107-0001","amount":"25.00","currency":"USDT","payee_sub":"2f6c0d1e8a9b4c7d","description":"Referral reward"}'

{
  "trace_id": "string",
  "status_code": 200,
  "message": "success",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "string",
    "order_type": "PAYMENT",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "40.00",
    "fee_amount": "40.00",
    "net_amount": "40.00",
    "currency": "USDT",
    "description": "string",
    "user_sub": "string",
    "checkout_url": "https://…",
    "expires_at": "2026-11-07T09:00:00Z",
    "completed_at": "2026-11-07T09:00:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

为此请求签名

订单

查询收款、退款和付款订单。

查询订单

GET/open/v1/orders/{id}

按 HTP 订单 id 查询收款、退款或付款单。只能查询当前 API Key 所属环境的订单，另一环境的订单返回 ORDER_NOT_FOUND。

请求头

X-Key-Idstring必填

签名请求头，见「请求签名」。

X-Timestampstring必填

签名请求头，见「请求签名」。

X-Noncestring必填

签名请求头，见「请求签名」。

X-Signaturestring必填

签名请求头，见「请求签名」。

路径参数

idstring · uuid必填

创建订单时返回的 HTP 订单 id（UUID）。

响应

200 · Order

错误码

401SIGNATURE_INVALID — missing headers, unknown or revoked key, wrong signature, timestamp outside the window, or a reused nonce.
404ORDER_NOT_FOUND — no such order for this app in the key's environment.
429TOO_MANY_REQUESTS — rate limit per app (default 600 requests/minute). Honour Retry-After.

# Sign first — see /docs/authentication or /tools/signature
curl -X GET '/open/v1/orders/0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d' \
  -H 'X-Key-Id: $HTP_KEY_ID' \
  -H 'X-Timestamp: $TS' \
  -H 'X-Nonce: $NONCE' \
  -H 'X-Signature: $SIGNATURE'

{
  "trace_id": "string",
  "status_code": 200,
  "message": "success",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "string",
    "order_type": "PAYMENT",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "40.00",
    "fee_amount": "40.00",
    "net_amount": "40.00",
    "currency": "USDT",
    "description": "string",
    "user_sub": "string",
    "checkout_url": "https://…",
    "expires_at": "2026-11-07T09:00:00Z",
    "completed_at": "2026-11-07T09:00:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

为此请求签名

按单号查询

GET/open/v1/orders

按你自己的订单号查询，用于创建请求超时后的恢复。查询串是签名 PATH 的一部分，须与实际发送的完全一致（如 /open/v1/orders?out_order_no=A1&order_type=PAYMENT）。

请求头

X-Key-Idstring必填

签名请求头，见「请求签名」。

X-Timestampstring必填

签名请求头，见「请求签名」。

X-Noncestring必填

签名请求头，见「请求签名」。

X-Signaturestring必填

签名请求头，见「请求签名」。

查询参数

out_order_nostring必填

你的 out_order_no（退款用 out_refund_no）。

order_typestring

订单类型，默认 PAYMENT。

PAYMENTREFUNDPAYOUT

响应

200 · Order

错误码

400INVALID_REQUEST — a field failed validation; message says which. Also returned when Idempotency-Key is missing or malformed.
401SIGNATURE_INVALID — missing headers, unknown or revoked key, wrong signature, timestamp outside the window, or a reused nonce.
404ORDER_NOT_FOUND — no such order for this app in the key's environment.
429TOO_MANY_REQUESTS — rate limit per app (default 600 requests/minute). Honour Retry-After.

# Sign first — see /docs/authentication or /tools/signature
curl -X GET '/open/v1/orders?out_order_no=A20261107-0001' \
  -H 'X-Key-Id: $HTP_KEY_ID' \
  -H 'X-Timestamp: $TS' \
  -H 'X-Nonce: $NONCE' \
  -H 'X-Signature: $SIGNATURE'

{
  "trace_id": "string",
  "status_code": 200,
  "message": "success",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "string",
    "order_type": "PAYMENT",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "40.00",
    "fee_amount": "40.00",
    "net_amount": "40.00",
    "currency": "USDT",
    "description": "string",
    "user_sub": "string",
    "checkout_url": "https://…",
    "expires_at": "2026-11-07T09:00:00Z",
    "completed_at": "2026-11-07T09:00:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

为此请求签名

回调（Webhook）

回调接入指南 →

POST

payment.paid

用户已支付。data 为收款单，状态 PAID，user_sub 已填写。

请求头

X-Eventstring必填

payment.paidpayment.refundedpayout.completed

X-Timestampstring必填

Unix seconds when HTP signed this delivery. Reject deliveries older than 5 minutes.

X-Noncestring必填

Random per delivery attempt.

Idempotency-Keystring必填

Equals event_id. The same event keeps its ID across retries — de-duplicate on it.

X-Signaturestring必填

Same scheme as requests, signed with your callback signing secret:

base64(HMAC-SHA256(callback_secret, "POST\n" + path_and_query_of_your_callback_url + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + event_id + "\n" + hex(sha256(raw_body))))

{
  "event_id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
  "event": "payment.paid",
  "created_at": "2026-11-07T09:05:12Z",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "A20261107-0001",
    "order_type": "PAYMENT",
    "environment": "SANDBOX",
    "status": "PAID",
    "amount": "40.00",
    "refunded_amount": "0.00",
    "fee_amount": "0.40",
    "net_amount": "39.60",
    "currency": "USDT",
    "description": "Premium membership, 1 month",
    "user_sub": "2f6c0d1e8a9b4c7d",
    "expires_at": "2026-11-07T09:30:00Z",
    "completed_at": "2026-11-07T09:05:12Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

POST

payment.refunded

退款成功。data 为退款单（order_type 为 REFUND，parent_id 为原收款单）。

请求头

X-Eventstring必填

payment.paidpayment.refundedpayout.completed

X-Timestampstring必填

Unix seconds when HTP signed this delivery. Reject deliveries older than 5 minutes.

X-Noncestring必填

Random per delivery attempt.

Idempotency-Keystring必填

Equals event_id. The same event keeps its ID across retries — de-duplicate on it.

X-Signaturestring必填

Same scheme as requests, signed with your callback signing secret:

base64(HMAC-SHA256(callback_secret, "POST\n" + path_and_query_of_your_callback_url + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + event_id + "\n" + hex(sha256(raw_body))))

{
  "event_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
  "event": "payment.paid",
  "created_at": "2026-11-07T09:00:00Z",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "string",
    "order_type": "PAYMENT",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "40.00",
    "fee_amount": "40.00",
    "net_amount": "40.00",
    "currency": "USDT",
    "description": "string",
    "user_sub": "string",
    "checkout_url": "https://…",
    "expires_at": "2026-11-07T09:00:00Z",
    "completed_at": "2026-11-07T09:00:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

POST

payout.completed

付款成功。data 为付款单（order_type 为 PAYOUT）。

请求头

X-Eventstring必填

payment.paidpayment.refundedpayout.completed

X-Timestampstring必填

Unix seconds when HTP signed this delivery. Reject deliveries older than 5 minutes.

X-Noncestring必填

Random per delivery attempt.

Idempotency-Keystring必填

Equals event_id. The same event keeps its ID across retries — de-duplicate on it.

X-Signaturestring必填

Same scheme as requests, signed with your callback signing secret:

base64(HMAC-SHA256(callback_secret, "POST\n" + path_and_query_of_your_callback_url + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + event_id + "\n" + hex(sha256(raw_body))))

{
  "event_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
  "event": "payment.paid",
  "created_at": "2026-11-07T09:00:00Z",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "string",
    "order_type": "PAYMENT",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "40.00",
    "fee_amount": "40.00",
    "net_amount": "40.00",
    "currency": "USDT",
    "description": "string",
    "user_sub": "string",
    "checkout_url": "https://…",
    "expires_at": "2026-11-07T09:00:00Z",
    "completed_at": "2026-11-07T09:00:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

对象

Order

idstring · uuid必填

HTP 订单 ID。

out_order_nostring必填

你的订单号（退款为 out_refund_no）。

order_typestring必填

PAYMENTREFUNDPAYOUT

parent_idstring · uuid

仅退款单：被退款的收款单。

environmentstring必填

SANDBOXPRODUCTION

statusstring必填

收款单：CREATED → PAID 或 CLOSED（已关闭或已过期）。退款、付款：SUCCEEDED。

CREATEDPAIDCLOSEDSUCCEEDED

amountstring必填

订单金额。

refunded_amountstring必填

仅收款单：累计已退款金额。

fee_amountstring必填

收款单的平台手续费；退款和付款为 0.00。

net_amountstring必填

收款单为你实际入账金额（amount - fee_amount）；退款、付款等于 amount。

currencystring必填

USDT

descriptionstring

user_substring

用户在你的开发者账号下的 OIDC sub。未指定 payer_sub 且未支付时为空。

checkout_urlstring · uri

仅 CREATED 且未过期的收款单返回，需在 HTP App 内打开。

expires_atstring · date-time

收款单的支付截止时间。

completed_atstring · date-time

支付成功 / 完成时间。

created_atstring · date-time必填

创建时间。

{
  "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
  "out_order_no": "string",
  "order_type": "PAYMENT",
  "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
  "environment": "SANDBOX",
  "status": "CREATED",
  "amount": "40.00",
  "refunded_amount": "40.00",
  "fee_amount": "40.00",
  "net_amount": "40.00",
  "currency": "USDT",
  "description": "string",
  "user_sub": "string",
  "checkout_url": "https://…",
  "expires_at": "2026-11-07T09:00:00Z",
  "completed_at": "2026-11-07T09:00:00Z",
  "created_at": "2026-11-07T09:00:00Z"
}

WebhookEvent

event_idstring · uuid必填

事件唯一 ID，重试时不变，请据此去重。

eventstring必填

payment.paidpayment.refundedpayout.completed

created_atstring · date-time必填

dataobject必填

与查询接口相同的订单对象。

data.idstring · uuid必填

HTP order ID.

data.out_order_nostring必填

Your order number (out_refund_no for refunds).

data.order_typestring必填

PAYMENTREFUNDPAYOUT

data.parent_idstring · uuid

Refunds only — the payment that was refunded.

data.environmentstring必填

SANDBOXPRODUCTION

data.statusstring必填

PAYMENT: CREATED → PAID or CLOSED (closed or expired). REFUND and PAYOUT: SUCCEEDED.

CREATEDPAIDCLOSEDSUCCEEDED

data.amountstring必填

USDT amount, positive, at most two decimals. Responses always use two decimals.

data.refunded_amountstring必填

Payments only — total refunded so far.

data.fee_amountstring必填

Platform fee on a payment. 0.00 on refunds and payouts.

data.net_amountstring必填

What your wallet received for a payment (amount - fee_amount); equals amount for refunds and payouts.

data.currencystring必填

USDT

data.descriptionstring

data.user_substring

The user's OIDC sub for your developer account. Empty on an unpaid payment without payer_sub.

data.checkout_urlstring · uri

Only on CREATED, unexpired payments. Open it inside the HTP App.

data.expires_atstring · date-time

data.completed_atstring · date-time

data.created_atstring · date-time必填

{
  "event_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
  "event": "payment.paid",
  "created_at": "2026-11-07T09:00:00Z",
  "data": {
    "id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "out_order_no": "string",
    "order_type": "PAYMENT",
    "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
    "environment": "SANDBOX",
    "status": "CREATED",
    "amount": "40.00",
    "refunded_amount": "40.00",
    "fee_amount": "40.00",
    "net_amount": "40.00",
    "currency": "USDT",
    "description": "string",
    "user_sub": "string",
    "checkout_url": "https://…",
    "expires_at": "2026-11-07T09:00:00Z",
    "completed_at": "2026-11-07T09:00:00Z",
    "created_at": "2026-11-07T09:00:00Z"
  }
}

Error

trace_idstring必填

联系客服时请提供。

status_codeinteger必填

与 HTTP 状态码相同。

messagestring必填

给开发者看的英文说明，不要据此判断。

error_codestring必填

稳定的错误码，请据此判断分支。

INVALID_REQUESTSIGNATURE_INVALIDREPLAY_PROTECTION_UNAVAILABLEIDEMPOTENCY_KEY_REUSEDIDEMPOTENCY_IN_PROGRESSAPP_UNAVAILABLEPAYMENT_NOT_ENABLEDPAYOUT_NOT_ALLOWEDSANDBOX_USER_ONLYCURRENCY_NOT_SUPPORTEDINVALID_AMOUNTLIMIT_EXCEEDEDORDER_ALREADY_EXISTSORDER_NOT_FOUNDUSER_NOT_AUTHORIZEDSELF_PAYMENT_FORBIDDENREFUND_NOT_ALLOWEDREFUND_AMOUNT_EXCEEDEDINSUFFICIENT_BALANCEDEVELOPER_WALLET_UNAVAILABLEINVALID_STATETOO_MANY_REQUESTSINTERNAL_ERROR

{
  "trace_id": "string",
  "status_code": 0,
  "message": "string",
  "error_code": "INVALID_REQUEST"
}