前言
四方支付收银台支持代收(收款)和代付(付款),商户通过 Merchant API 创建对应的收银台会话。
- 创建代收收银台: 调用 创建代收(
POST /api/v1/pay/create),由用户选择支付通道并完成付款。 - 创建代付收银台: 调用 创建代付(
POST /api/v1/payout/create),由用户选择通道、确认收款资料并提交代付。
创建会话后,商户将返回的 payment_url 交给用户。用户在收银台选择通道并确认提交后,平台才生成正式订单;交易结果以订单查询或异步通知为准。
创建代收、代付收银台前,平台会检查商户通道绑定、环境、币种、支付类型、金额限额、有效费率及银行/支付方式映射。无法匹配可用通道时,接口直接返回错误,不保存新会话或返回 payment_url。代收不检查商户余额;代付要求当前同币种可用余额覆盖本金与匹配通道的商户手续费,不足返回 40001 / error.insufficient_balance。资料允许在收银台补填的字段仍可省略。
自由匹配创建未指定 channel_code 时,金额低于当前匹配范围内各通道配置的总体最低值返回 40002,高于总体最高值返回 40003。最低取各通道 min_amount 的最小值,最高取各通道 max_amount 的最大值;message 会直接显示币种和对应金额,例如 amount below minimum (MYR 10.00)、amount above maximum (MYR 2000.00)。存在未配置的边界时,该侧不限;区间内仍须通过各通道、API Key、商户、费率、银行及余额校验,不能据此保证下单成功。
银行、电子钱包和支付网络/方式统一使用平台代码,以 currency + code 区分。平台目录见 平台支付代码、币种目录 和 银行与支付代码目录;当前 Key 的可用交易选项以 通道可用选项 为准,目录不代表已开通交易能力。
阅读与接入#
接入开发 Flow#
- 准备凭证
- 验证签名
- 接入创建与查询
- 实现 Notify
- 收银台联调
- 获取测试环境的 API Base URL、
merchant_id、api_key和api_secret。 - 阅读 接入与认证 和 响应与订单约定,用固定签名示例验证签名。
- 按业务接入 代收 或 代付 的创建与查询。
- 按 异步通知 实现 Notify 验签、去重、状态更新和应答。
- 使用 完整示例与工具 完成测试环境联调。
交易 Flow(代收 / 代付)#
以下为收银台交易的正常流程。查询和 Notify 是两条结果同步路径,不需要等待两者同时完成。
- 商户服务端:创建会话生成并保存
merchant_order_no,调用代收/api/v1/pay/create或代付/api/v1/payout/create。 - 平台:返回收银台地址保存
platform_order_no与payment_url。此时只是收银台会话,尚未生成正式订单。 - 用户:在收银台确认打开
payment_url,选择通道、补充必要资料并确认提交;平台生成正式订单并处理交易。 - 商户:同步交易结果主动查询服务端调用代收
/api/v1/pay/query或代付/api/v1/payout/query,读取会话或正式订单状态。异步 Notify配置通知地址后接收平台通知;验签、校验并去重处理,成功后返回SUCCESS。 - 商户:更新订单并显示结果代收
paid、代付success表示成功。创建会话成功、获得收银台地址或浏览器返回都不代表交易成功。
查询与结果处理#
| 场景 | 接入方处理 |
|---|---|
查询返回 checkout_mode=cashier |
尚未生成正式订单,按会话状态等待选择、继续查询或处理会话过期。 |
| 正式订单仍在处理中 | 代收 created / pending / manual_review,代付 reviewing / processing,继续查询或等待通知。 |
| 获得交易结果 | 根据代收或代付的状态说明更新本地订单;查询和 Notify 不重复处理同一结果,更正通知按版本处理。 |
| 创建超时、断线或结果不明 | 使用原订单号查询,不更换订单号重复创建。 |
| 用户从收银台返回 | 服务端查询当前结果,再向用户展示,不依据跳转判定成功。 |