API 文档中使用的规范定义。
请求标头
| 标题 | 必填 | 定义 |
|---|
| x-api-key | 是的 | API-在应用程序中颁发的密钥（“业务”部分）。该组织是从请求主机解析的 |
| Content-Type | 是（POST） | application/json 用于创建请求 |
金额及币种
| 术语 | 定义 |
|---|
| amount | 以最小货币单位表示的整数字符串（例如分、最小标记分数） |
| amount_with_fee | 金额加申请费（最小货币单位） |
| currency | ISO 类货币/代币代码（例如 USDT） |
| currency_dest | 用于转换的目标货币 (FX)。选修的;默认为 currency |
标识符
| 术语 | 定义 |
|---|
| id | 交易内部系统UUID |
| txid | 客户提供的标识一项业务操作的字符串； UUID 是一个方便的选择，不是必需的格式 |
路由参数
| 术语 | 定义 |
|---|
| route | 为API密钥配置的处理路径别名 |
| env | prod（默认）。打开并确认请求时保留该值。 |
状态生命周期
| 状态 | 意义 |
|---|
| created | 已接受，等待处理 |
| new | 处理开始前的初始状态 |
| authorizing | 授权进行中 |
| pre_authorized_3ds | 等待3DS认证 |
| action_required | 等待额外的操作（3DS/额外授权） |
| charging | 进行中（授权/资助） |
| payment_suspended | 入境交易暂停 |
| payout_suspended | 出境交易暂停 |
| charged | 成功完成（最终状态） |
| reversed | 冲正（最终状态） |
| refunded | 退款（最终状态） |
| rejected | 无法挽回地失败（最终状态） |
| failed | 失败（最终状态） |
最终状态为charged、reversed、refunded、rejected、failed。最常见的正常流程是created → charging → charged。
时间字段
| 领域 | 定义 |
|---|
| started | ISO 处理开始时的时间戳 |
| finished | ISO 处理完成时的时间戳；从状态决定结果 |
货币存储对象
| 领域 | 定义 |
|---|
| network | 区块链网络（ETH、TRX等） |
| type | 工具类型（bank_card、p2p_proxy 等） |
| wallet_id | 内部钱包标识符（支付/支付目标） |
| cardnumber | 虚拟卡 PAN（在某些回复中被掩盖） |
| cvv | 虚拟卡安全码（不得以明文写入日志） |
| exp_month / exp_year | 卡到期值（字符串，零填充） |
| cardholder | 持卡人姓名（ASCII 或 UTF-8） |
错误字段
| 领域 | 定义 |
|---|
| error_description | 人类可读的失败原因（不稳定文本） |
幂等性指南
每个业务操作使用唯一的（幂等）txid，并在发送前将其保留。该值是一个字符串； UUID 生成很方便，但不需要 UUID 语法。在相同的账户中使用相同的标识符重试相同的指令。请勿将其重复用于不同的收件人或金额。超时后恢复原来的操作；重试不能默默地成为新的付款。
轮询策略
轮询读取具有有限的退避，例如 1s → 2s → 4s → 8s，交互预算为 30s。在已知的最终状态或预算到期时停止。超时时报告待定/未知结果并保留原始 id/txid。未知的状态并不代表成功。请参阅错误和重试。
Webhooks（信息）
Webhooks 指示状态更改，但不具有权威性。始终通过 GET 交易确认。
金额精度
金额是最小货币单位的整数字符串，而不是浮点值。从GET https://app.heth.me/api/v1/contracts?env=prod中获取货币、网络的小数位数。 USDT/ETH 和 USDT/TRX 目前使用 6 小数：1 USDT = "1000000"、0.25 USDT = "250000"。 ETH 有 18 小数位；这并不适用于以太坊上的每个代币。未知的金额精度必须停止金额转换。请参阅API 架构。