文档使用方法
阅读与接入#
接入开发 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 不重复处理同一结果,更正通知按版本处理。 |
| 创建超时、断线或结果不明 | 使用原订单号查询,不更换订单号重复创建。 |
| 用户从收银台返回 | 服务端查询当前结果,再向用户展示,不依据跳转判定成功。 |
状态定义见 响应与订单约定、代收查询 和 代付查询;通知处理见 异步通知。
AI 协助开发(可选)#
把 文档主页 的可访问链接与下面的提示词交给 AI,无需附件。让 AI 阅读本次接入所需的分类页面;无法打开链接时,直接粘贴相关章节。
说明项目技术栈、本次接入范围、相关代码路径和测试命令即可。
AI 开发提示词(可直接复制)#
替换尖括号内容后整体复制。提示词已包含签名、请求与通知处理规则;完整字段和示例可从文档主页补充。
你是我的后端集成工程师。请在现有 <语言/框架> 项目中接入“四方支付 Merchant API”。
文档链接:<AI 可访问的文档主页 URL>
API Base URL:<平台提供的当前环境地址>
本次范围:
- 环境:<staging>
- 业务:<代收 / 代付>
- 功能:<创建、查询、Notify>
- 不做:<明确排除的功能>
现有项目:
- HTTP Client:<组件或文件>
- 配置变量名:<名称>
- 订单 Service/Repository:<路径>
- Notify 路由与幂等存储:<路径或说明>
- 测试命令:<命令>
一、请求与认证
- 使用 HTTPS POST,Content-Type: application/json;API Base URL 决定环境,不通过请求参数切换。
- 由服务端读取 merchant_id、api_key、api_secret;api_secret 只作为签名密钥,不放进请求体。
- 签名接口在业务字段外加入 api_key、merchant_id、timestamp、nonce、sign。
- timestamp 是当前 Unix 秒时间戳字符串,不是毫秒;nonce 每次使用新的随机串。
- 请求体是单层 JSON 对象,不接受 null、数组或嵌套对象。金额用十进制字符串,如 "100.00"。
- 代收:POST /api/v1/pay/create、POST /api/v1/pay/query。
- 代付:POST /api/v1/payout/create、POST /api/v1/payout/query。
- 余额:POST /api/v1/balance/query;通道可用选项:POST /api/v1/channel/options。以上均需签名。
- 币种目录:POST /api/v1/currency/options,请求体仅 {"api_key":"<API_KEY>"}。
- 银行与支付代码目录:POST /api/v1/bank/options,请求体为 {"api_key":"<API_KEY>","currency":"MYR"}。
这两个目录接口无需 merchant_id、timestamp、nonce、sign;目录不代表当前 Key 已开通交易能力。
二、签名算法(HMAC-SHA256,不是请求体加密)
请实现可复用的 canonicalString(parameters)、sign(parameters, apiSecret) 和 verifySignature(...):
1. 从完整请求字段中排除 sign;不要只签名公共字段或固定白名单。
2. 仅排除值为 "" 的字段;0、false 和包含空格的非空字符串不能丢弃。
3. 按字段名 ASCII 升序排序,不使用地区语言排序。
4. 用原始标量字符串拼接 key=value。字符串不加引号、不 trim;数字保留发送时的表示,布尔值为 true/false。
5. 用 & 连接各项,不进行 URL Encode。不要对 JSON 序列化结果签名,也不要把金额 "100.00" 改成 "100"。
6. canonical string 与 api_secret 使用 UTF-8;api_secret 作为 HMAC key,不拼接在待签名字符串末尾。
7. 输出 64 位小写十六进制字符串,放入请求体 sign;不使用 Base64、MD5、普通 SHA-256 或 Bearer Token。
算法表达式:
canonical = join("&", ASCII_SORT_KEYS(parameters excluding sign and empty strings).map(key => key + "=" + rawScalarString(parameters[key])))
sign = HEX_LOWER(HMAC_SHA256(key=UTF8(api_secret), message=UTF8(canonical)))
固定单元测试向量(时间戳仅用于离线测试,不用于实际请求):
api_secret = test_secret_123
parameters = {"api_key":"test_key","merchant_id":"merchant_1001","nonce":"nonce_001","platform_order_no":"P202608120001","timestamp":"1786502400"}
canonical = api_key=test_key&merchant_id=merchant_1001&nonce=nonce_001&platform_order_no=P202608120001×tamp=1786502400
sign = 03b28189b1d613de76f444db1ffb834daefd609e2eee65d4871b34db8818bd73
每次请求或重试重新生成 timestamp、nonce、sign。时间窗口通常为前后 300 秒,以平台配置为准。
三、创建、查询与收银台
- 代收最小请求体如下;timestamp、nonce 动态生成,sign 按上述算法计算后填入:
{"api_key":"<API_KEY>","merchant_id":"<MERCHANT_ID>","merchant_order_no":"<已保存的商户订单号>","amount":"100.00","currency":"MYR","timestamp":"<当前Unix秒>","nonce":"<新随机串>","sign":"<计算结果>"}
- 代付也必须提交 merchant_order_no、amount、currency;bank_code、account_no、account_name、recipient_email 可预填,未填资料在收银台补齐。其余字段按对应接口页面实现。
- 创建前保存唯一 merchant_order_no。相同订单号重试保持全部业务参数不变,只更新 timestamp、nonce、sign。
- 同时检查 HTTP 状态和 JSON code;code=0 只代表接口请求成功。响应包含 code、message、data、request_id;业务错误还包含 message_key、default_message。
- 首次创建返回 checkout_mode=cashier、status=awaiting_payment_method、platform_order_no、payment_url;此时尚未生成正式订单。
- 保存并原样使用 payment_url,让前端跳转收银台。用户选择通道、确认资料后才生成正式订单。
- 查询用 platform_order_no 或 merchant_order_no,至少一个;同时提供时必须指向同一笔交易。
- 查询会话不返回 payment_url;正式订单查询的 checkout_mode=direct 表示进入正式订单阶段,不代表商户改用其他创建方式。
- 代收 status=paid、代付 status=success 表示交易成功;创建成功、取得 payment_url 或浏览器返回都不是交易成功依据。
- 超时、断线或非零 code 后,使用原订单号查询,不换新订单号重复创建,也不直接判定交易失败。
四、Notify 验签与处理
1. 接收单层 JSON,保留所有字段的原始标量字符串;先取得 sign,再按“二、签名算法”重算。
event_type、timestamp、nonce、secret_version 以及收到的所有非空业务字段都参与签名;revision、correction 等可选字段存在时也必须参与。
2. 使用本次接入凭证对应的 api_secret,并核对 secret_version;校验 sign 为 64 位小写 hex,用恒定时间比较,校验秒级 timestamp 的允许时间窗口。
3. 验签通过后,校验商户订单归属、平台与商户订单号、金额、币种,以及 event_type 和 status 的对应关系,再修改订单。
4. 支持以下通知:payin.succeeded → paid;payin.failed → failed;payin.expired → expired;
payout.succeeded → success;payout.failed → failed;cashier.payin.expired / cashier.payout.expired → expired。
会话过期支持 reason_code=cashier_channel_not_selected 或 cashier_submission_timeout;正式代收超时为 order_timeout。
5. 普通通知按 event_type + platform_order_no 去重;状态更正按 event_type + platform_order_no + status_revision 去重;
会话过期按 event_type + platform_order_no + expiry_revision 去重,expiry_revision 缺省按 0。
注意:缺省版本只用于去重,不得在验签前往通知中补入原本不存在的字段。
6. 更正通知含正整数字符串 status_revision 和 correction="true";保存已处理的最高版本,旧通知不能覆盖新状态。
在同一业务事务内完成订单与必要账务处理;重复通知不重复入账,更正按现有业务规则调整,不将每次成功通知当成新增入账。
7. 成功处理或确认已处理的重复通知,返回 HTTP 2xx、Content-Type: text/plain,正文为 SUCCESS,不返回 JSON。
验签失败或业务处理失败不返回 SUCCESS。
五、实现与验证
- 先检查现有代码并列出影响文件,按“签名 → 创建/查询 Client → Notify → 收银台联调”实现本次范围。
- 复用现有 HTTP Client、配置与订单模块;未经确认不改 Schema、权限或资金流程,不增加新包。
- 测试固定签名向量、空字符串与 0/false、含空格/&/中文的字段、金额格式、业务错误、超时后查询、Notify 错签、重复通知和版本乱序。
- 从文档主页补充所需接口字段、状态说明、完整示例和 OpenAPI。无法读取或资料冲突时指出缺少/冲突的具体内容,不自创接口规则。
- 完成后输出修改摘要、变更文件、测试结果和手工联调步骤。
按场景追加#
按任务在主提示词末尾追加一项:
- 只做 API Client:
只实现签名、请求、响应解析、超时处理和单元测试;不接订单表、不建 Notify 路由、不改 Schema。 - 只做 Notify:
只实现 Notify 验签、去重、状态更新和应答;不修改创建/查询 Client。先列出 event_type、status、去重键和 revision 规则。 - 审查现有实现:
只审查,不修改代码。按严重程度列出有文件和行号的问题、测试缺口及需要人工确认的事项。 - 协助排错:
先诊断,不改代码。根据接口、HTTP 状态、code、message_key、request_id、字段名、本地时间和已执行步骤,给出最可能原因和最小验证步骤。