创建收款单

POST {BASE_URL}/api/v1/open/charges

请求体为 strict 模式：仅支持下列字段，多余字段将导致 400。

账单地址须在建单时一次性预填（billing_address 必填）。

请求头

头	必填	说明
Authorization	是	Bearer + 完整 API 密钥
Content-Type	是	application/json
Idempotency-Key	否	同一商户下唯一；建议 UUID；最大 128 字符。重复请求返回首次建单结果（HTTP 200）

请求体

字段	类型	必填	说明
merchant_order_id	string	是	业务单号；同一商户下不可重复
sales_channel	string	是	销售渠道编码
customer_region	string	是	客户所在国家或地区代码。请传大写 ISO 3166-1 alpha-2 编码（如 US、GB、HK），且须为平台已启用的订单地区；通常应与 billing_address.country 保持一致
amount	number	是	金额，须 > 0
currency	string	是	货币代码（平台白名单）
description	string	是	订单描述（展示给付款人）
original_amount	number | null	否	原价
internal_note	string	否	内部备注
expires_minutes	number	否	链接有效分钟数，默认 1440，范围 5～43200
notify_url	string	否	服务端 Webhook：本笔订单 PAID / FAILED，以及物流事件 SHIPPED / LOGISTICS_UPDATED 时，向该 URL 发送与 支付结果回调 相同格式与签名的 POST。须为 https，最长 2048。查询接口不返回此字段
return_url	string	否	客户浏览器回跳：支付完成/失败/过期，或客户点击返回商户站点时跳转。须为 https，最长 2048。查询串附带 payment_result（succeeded | failed | expired | pending）、pay_order_id（平台订单 UUID）；若有业务单号则附带 merchant_order_id。查询接口不返回此字段
checkout_host	string	否	可选，指定客户打开的收银台域名。纯主机名或 HTTPS 根 URL。v1 用于匹配通道；v2 作为选域偏好，最终以响应中的 payment_url 为准
payment_methods	string[]	否	v2：创单勾选方式；省略则用默认勾选 ∩ 可用。v1 商户请勿传。与 gateway_id 互斥
billing_address	object	是	账单地址，见下表
retry_of	string (uuid)	否	失败重试：前序支付单的 order.id。须为本商户订单；不存在或跨商户返回 404，前序单已支付返回 409。重试单须使用新的 merchant_order_id。未同时传 gateway_id 时，平台会避开该组已用过的支付通道，无可用时回退仍建单。建单前可先查是否需要重试。完整流程见 失败后重新建单
gateway_id	string (uuid)	否	人工指定支付通道。取值来自 获取可用支付通道 的 gateway_id。传入则该笔订单按 V1 收银台建单。与 payment_methods 互斥

若商户已切换为收银台 V2，成功响应中的 payment_url 路径为 /checkout/{charge_code}（单域、无跨域跳转），并可能返回 effective_payment_methods。版本由平台/商户配置决定，对接方无需传 checkout_version。例外：传了 gateway_id 的订单始终走 V1，payment_url 为 /pay/{charge_code}，收银域名可能与平时不同。

指定支付通道

需要运营在失败后指定某一通道再发链接时：

1. 调用 获取可用支付通道（失败救单请带 retry_of）。
2. 从列表中选取 gateway_id（避开 used_in_retry_group / shares_account_with_retry_group 为 true 的项）。
3. POST /charges 传入该 gateway_id。可与 retry_of 同传；不要同时传 payment_methods。
4. 使用返回的新 payment_url，并停止分发旧链接。

指定通道时：

• 本笔强制按 V1 建单，无视商户当前是 V1 还是 V2。
• checkout_host 会被忽略（通道已给定）。
• 与 retry_of 同传时跳过「避开已用通道」的自动排除，但仍拒绝「该通道绑定账号与前序失败单相同」的选择（422）。

完整组合与回收旧链接说明见 失败后重新建单。

billing_address

字段	类型	必填	说明
name	string	是	姓名（去首尾空格后非空）
phone_national	string	是	国内手机号，仅数字、不含国家码；位数须符合该国规则（见下方）
email	string	是	合法邮箱
country	string	是	大写 ISO 3166-1 alpha-2（如 US）；须为平台已启用的账单国家
state	string	视国家	ISO 3166-2 全码（如 US-NY、CA-ON）。该国有一级区划表时必填；无区划国（如 HK）可留空
city	string	是	城市
address1	string	是	街道地址
address2	string	否	第二行地址
zip	string	视国家	有邮编规则的国家必填且须匹配格式；无规则国（如 HK）可选

手机号

请传去掉国家码后的国内号。若误传含 + 或国家码前缀的 E.164，可能导致位数校验失败（400）。

phone_national 位数（摘要）

country	区号	国内位数
US / CA	+1	10
GB	+44	10–11
IE	+353	7–9
FR	+33	9
DE	+49	10–11
NL	+31	9
BE	+32	8–9
AU	+61	9–10
NZ	+64	8–11

其他已启用国家的位数与邮编规则以平台校验为准；不确定时请用真实样例调用并根据错误信息调整。

state 示例

country	state 示例
US	US-NY、US-CA、US-TX
CA	CA-ON、CA-BC、CA-QC
GB	GB-ENG、GB-SCT、GB-WLS
AU	AU-NSW、AU-VIC、AU-QLD（或平台接受的等价编码，以校验为准）
DE	DE-BE、DE-BW、DE-NW
FR	FR-IDF、FR-ARA、FR-PAC

请使用编码值，勿使用地区全称。

zip 示例

country	规则摘要	合法示例
US	5 位或 5+4	94103、94103-1234
CA	加拿大邮编	K1A 0B6、M5H2N2
GB	英国邮编	SW1A 1AA
IE	Eircode	D02 X285
HK	无固定规则 → 可选	（可留空）

成功响应

201 Created（幂等重复命中为 200 OK，体结构相同）

{
  "order": {
    "id": "<payment_order.uuid>",
    "merchant_order_id": "...",
    "charge_code": "...",
    "status": "PENDING",
    "amount": 99.0,
    "currency": "USD",
    "description": "...",
    "paid_at": null,
    "created_at": "...",
    "expires_at": "...",
    "payment_url": "https://...",
    "settled_via": "ONLINE",
    "crypto_payment": null,
    "shipping": {
      "shipping_carrier": null,
      "tracking_no": null,
      "shipping_note": null,
      "shipped_at": null
    }
  },
  "payment_url": "https://..."
}

• order.id：后续查询与 Webhook 的主键（UUID）
• payment_url：客户支付链接
• order.shipping：物流信息；未发货时各字段可为 null

常见错误

HTTP	说明
400	JSON / 字段校验失败；或 checkout_host 无法解析；或同时传了 gateway_id 与 payment_methods
401	鉴权失败
404	retry_of 指向的订单不存在或不属于当前商户
409	merchant_order_id 重复；或 retry_of 指向的订单已支付
422	当前订单参数无法创建收款单（如地区/币种/金额组合不受支持）；指定的 gateway_id 不存在/未开放/当前参数下不可用；或该通道与前序失败单使用同一收款账号
429	限流
503	服务暂时不可用（如商户侧前置条件未就绪）