创建收款单

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	是	客户地区（须在平台地区白名单内）
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	否	可选，指定客户打开的收银台域名。纯主机名（如 pay.example.com）或 HTTPS 根 URL（如 https://pay.example.com/）；须为有效主机名
billing_address	object	是	账单地址，见下表

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 无法解析
401	鉴权失败
409	merchant_order_id 重复
422	当前订单参数无法创建收款单（如地区/币种/金额组合不受支持）
429	限流
503	服务暂时不可用（如商户侧前置条件未就绪）