文档目录 · 前言

前言

四方支付收银台支持代收(收款)和代付(付款),商户通过 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#

  1. 准备凭证
  2. 验证签名
  3. 接入创建与查询
  4. 实现 Notify
  5. 收银台联调
  1. 获取测试环境的 API Base URL、merchant_id、api_key 和 api_secret。
  2. 阅读 接入与认证 和 响应与订单约定,用固定签名示例验证签名。
  3. 按业务接入 代收 或 代付 的创建与查询。
  4. 按 异步通知 实现 Notify 验签、去重、状态更新和应答。
  5. 使用 完整示例与工具 完成测试环境联调。

交易 Flow(代收 / 代付)#

以下为收银台交易的正常流程。查询和 Notify 是两条结果同步路径,不需要等待两者同时完成。

  1. 商户服务端:创建会话生成并保存 merchant_order_no,调用代收 /api/v1/pay/create 或代付 /api/v1/payout/create。
  2. 平台:返回收银台地址保存 platform_order_no 与 payment_url。此时只是收银台会话,尚未生成正式订单。
  3. 用户:在收银台确认打开 payment_url,选择通道、补充必要资料并确认提交;平台生成正式订单并处理交易。
  4. 商户:同步交易结果
    主动查询服务端调用代收 /api/v1/pay/query 或代付 /api/v1/payout/query,读取会话或正式订单状态。
    异步 Notify配置通知地址后接收平台通知;验签、校验并去重处理,成功后返回 SUCCESS。
  5. 商户:更新订单并显示结果代收 paid、代付 success 表示成功。创建会话成功、获得收银台地址或浏览器返回都不代表交易成功。

查询与结果处理#

场景 接入方处理
查询返回 checkout_mode=cashier 尚未生成正式订单,按会话状态等待选择、继续查询或处理会话过期。
正式订单仍在处理中 代收 created / pending / manual_review,代付 reviewing / processing,继续查询或等待通知。
获得交易结果 根据代收或代付的状态说明更新本地订单;查询和 Notify 不重复处理同一结果,更正通知按版本处理。
创建超时、断线或结果不明 使用原订单号查询,不更换订单号重复创建。
用户从收银台返回 服务端查询当前结果,再向用户展示,不依据跳转判定成功。

状态定义见 响应与订单约定、代收查询 和 代付查询;通知处理见 异步通知。

搜索文档