主题
买单接口（买入USDT）
商户买入 USDT，系统自动匹配交易员收款。
流程： 商户创建订单 → 自动匹配交易员 → 交易员收到款项 → 交易员确认收款 → 通知商户回调。
端点
| 接口 | 路径 | 三要素验证 |
|---|---|---|
| 真实接口（默认） | POST /merchant/createOrder | 按合作约定 |
| 测试接口 | POST /test/createOrder | ✘ 跳过 |
三要素校验说明
三要素（customer_name / id_card / mobile）字段均为选填，是否需要提供请向商务人员确认。约定执行实名验证时：验证未通过的买单将暂存并返回补全链接（见下方「三要素验证失败处理」），卖单验证失败直接返回错误；约定免验证时：直接建单，result_status 恒为 success。
TIP
买单不需要提供客户的支付方式，系统会自动匹配有收款方式且符合金额区间的交易员，按交易员最后接单时间轮询。默认只匹配银行卡类型的交易员；如需匹配微信或支付宝，通过 method_type 参数指定。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
order_type | int | 是 | 订单类型，买单固定为 1 |
cny_amount | decimal | 是 | 买入 CNY 金额，必须大于 0 |
customer_name | string | 否 | 客户姓名（是否必填请向商务人员确认） |
id_card | string | 否 | 客户身份证号，18 位（是否必填请向商务人员确认） |
mobile | string | 否 | 客户手机号，11 位（是否必填请向商务人员确认） |
merchant_order_no | string | 否 | 商户单号，商户自定义业务单号，用于对账（限长 255） |
method_type | string | 否 | 指定匹配交易员的收款方式类型：bank=银行卡（默认）、wechat=微信、alipay=支付宝。不传时默认匹配银行卡 |
另需携带 通用参数（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 | 订单编号 |
merchant_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",
"merchant_order_no": "MOC20260713001",
"status": "pending",
"order_type": 1,
"cny_amount": 1000.00,
"payment_method": {
"method_type": "bank",
"bank": "中国银行",
"sub_bank": "北京分行",
"card_number": "6217*********1234",
"account": "",
"qr_code": "",
"real_name": "李四"
},
"merchant_amount": 138.50,
"deposit_amount": 2.77,
"service_amount": 1.38,
"merchant_actual_amount": 134.35,
"createtime": 1699065600,
"pay_url": "https://api.pisces-pay.cn/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://api.pisces-pay.cn/addons/huanyu/order_identity/submit?token=a1b2c3d4e5f6...",
"expire_time": 1782600000
}
}处理建议
收到 pending_identity 时，请将 identity_url 下发给最终付款用户（短信 / 跳转 / 二维码均可）。用户在页面中补全三要素并通过验证后，订单会自动创建，页面跳转至收款信息页；用户无需返回商户系统再次下单。若用户补全失败（仅 1 次机会）或链接过期（2 小时），需商户重新调用本接口创建新订单。