主题
买单接口（买入USDT）
商户买入 USDT，系统自动匹配交易员收款。
流程： 商户创建订单 → 自动匹配交易员 → 交易员收到款项 → 交易员确认收款 → 通知商户回调。
端点
| 接口 | 路径 | 三要素验证 |
|---|---|---|
| 真实接口（默认） | POST /merchant/createOrder | ✔ 执行 |
| 免三要素版 | POST /merchant/createOrderSimple | ✘ 跳过 |
| 测试接口 | POST /test/createOrder | ✘ 跳过 |
TIP
买单不需要提供支付方式，系统会自动匹配有支付方式的交易员。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
order_type | int | 是 | 订单类型，买单固定为 1 |
cny_amount | decimal | 是 | 买入 CNY 金额，必须大于 0 |
customer_name | string | 是 | 客户姓名 |
id_card | string | 是 | 客户身份证号，18 位 |
mobile | string | 是 | 客户手机号，11 位 |
另需携带 通用参数（api_key / timestamp / nonce / signature）。
三要素验证失败处理（重要）
创建订单时若三要素验证未通过，订单不会直接失败，而是暂存订单草稿并返回 result_status = "pending_identity" 和一个 identity_url（三要素补全 H5 链接）。
商户需引导最终付款用户打开该链接，在页面中补全 / 修正三要素；补全通过后系统会重新匹配交易员并完成建单，页面自动跳转到收款信息页。
限制：
- 每个暂存单仅允许补全 1 次（补全提交的三要素再次验证失败即锁定）
- 有效期 2 小时，过期需重新下单
- 链接带一次性 token 鉴权
卖单不受此机制影响
卖单三要素失败仍直接返回错误。三要素验证通过时正常建单，返回 result_status = "success"。
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
result_status | string | 结果状态：success＝三要素通过、订单创建成功；pending_identity＝三要素未通过、订单已暂存，需引导用户打开 identity_url 补全。商户据此字段区分两种结果 |
result_status = "success" 时返回（订单已创建）
| 参数名 | 类型 | 说明 |
|---|---|---|
order_no | string | 订单编号 |
status | string | 订单状态（pending = 待支付） |
order_type | int | 订单类型（1 = 买入） |
cny_amount | decimal | CNY 金额 |
payment_method | object | 匹配的交易员支付方式 |
merchant_amount | decimal | 商户实际获得 USDT 数量 |
deposit_amount | decimal | 保证金金额 |
service_amount | decimal | 服务费金额 |
merchant_actual_amount | decimal | 商户实际到账 USDT 数量 |
createtime | int | 创建时间戳 |
pay_url | string | 订单详情页链接，浏览器打开可查看收款银行卡信息并上传转账凭证 |
result_status = "pending_identity" 时返回（订单已暂存，需补全三要素）
| 参数名 | 类型 | 说明 |
|---|---|---|
pending_no | string | 暂存单号 |
identity_url | string | 三要素补全 H5 链接（带一次性 token），引导付款用户在浏览器打开 |
expire_time | int | 暂存单过期时间戳（默认创建后 2 小时，过期需重新下单） |
pay_url 使用说明
该链接为订单详情页地址，请引导用户在浏览器中直接打开。页面将展示收款银行卡信息、转账金额，并支持上传转账凭证和取消订单。页面无需登录即可访问。
响应示例
示例一：三要素验证通过，订单创建成功（result_status = "success"）
json
{
"code": 1,
"msg": "订单创建成功",
"data": {
"result_status": "success",
"order_no": "ORD202511041234567890",
"status": "pending",
"order_type": 1,
"cny_amount": 1000.00,
"payment_method": {
"bank": "中国银行",
"sub_bank": "北京分行",
"card_number": "6217*********1234",
"real_name": "李四"
},
"merchant_amount": 138.50,
"deposit_amount": 2.77,
"service_amount": 1.38,
"merchant_actual_amount": 134.35,
"createtime": 1699065600,
"pay_url": "https://www.huanyu.com/addons/huanyu/order_page/detail?order_no=ORD202511041234567890"
}
}示例二：三要素验证未通过，订单已暂存（result_status = "pending_identity"）
json
{
"code": 1,
"msg": "需补充客户身份信息",
"data": {
"result_status": "pending_identity",
"pending_no": "PND202606281234567890",
"identity_url": "https://www.huanyu.com/addons/huanyu/order_identity/submit?token=a1b2c3d4e5f6...",
"expire_time": 1782600000
}
}处理建议
收到 pending_identity 时，请将 identity_url 下发给最终付款用户（短信 / 跳转 / 二维码均可）。用户在页面中补全三要素并通过验证后，订单会自动创建，页面跳转至收款信息页；用户无需返回商户系统再次下单。若用户补全失败（仅 1 次机会）或链接过期（2 小时），需商户重新调用本接口创建新订单。