API付款
1. 集成准备
上传测试商户公钥，获取平台公钥、AppID、测试商户号等集成信息；
配置回调地址（WebHook），包括支付结果回调地址、退款结果回调地址等；
理解请求报文加签和验签的原理，用于生成每次HTTP请求Header的
sign签名字符串。
2. 交互流程
2.1 付款-成功下单
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#e6f0ff',
'primaryTextColor': '#333',
'primaryBorderColor': '#5b9bd5',
'lineColor': '#888',
'actorMargin': 40,
'noteBkgColor': '#0056b3',
'noteTextColor': '#ffffff',
'noteBorderColor': '#004a99'
}
}}%%
sequenceDiagram
participant User as 用户
participant MServer as 商户服务端
participant PMServer as PayerMax 服务端
%% 1. 校验阶段
User->>MServer: 1.1 填写收款信息
MServer->>PMServer: 1.2 付款要素校验
PMServer->>PMServer: 1.3 验证PayerMax
内部字段规则
PMServer-->>MServer: 1.4 返回校验结果与报错
MServer-->>User: 1.5 提示用户修改
User->>MServer: 1.6 修改无误，提交保存
%% 2. 提款发起阶段
User->>MServer: 2.1 发起提款
MServer->>PMServer: 2.2 发起付款
PMServer->>PMServer: 2.3 校验、受理付款
%% 3. 结果回调阶段
PMServer->>MServer: 3.1 回调最终结果
MServer->>PMServer: 3.2 正确响应
MServer-->>User: 3.3 返回交易结果
2.2 付款-下单失败
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#e6f0ff',
'primaryTextColor': '#333',
'primaryBorderColor': '#5b9bd5',
'lineColor': '#888',
'actorMargin': 40,
'noteBkgColor': '#0056b3',
'noteTextColor': '#ffffff',
'noteBorderColor': '#004a99'
}
}}%%
sequenceDiagram
participant User as 用户
participant MServer as 商户服务端
participant PMServer as PayerMax 服务端
%% 1. 校验阶段
User->>MServer: 1.1 填写收款信息
MServer->>PMServer: 1.2 付款要素校验
PMServer->>PMServer: 1.3 验证PayerMax
内部字段规则
PMServer-->>MServer: 1.4 返回校验结果与报错
MServer-->>User: 1.5 提示用户修改
User->>MServer: 1.6 修改无误，提交保存
%% 2. 提款发起阶段
User->>MServer: 2.1 发起提款
MServer->>PMServer: 2.2 发起付款
PMServer->>PMServer: 2.3 校验、受理付款
%% 3. 失败反馈阶段
PMServer->>MServer: 3.1 失败响应
MServer-->>User: 3.2 返回交易结果
2.3 交易状态查询
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#e6f0ff',
'primaryTextColor': '#333',
'primaryBorderColor': '#5b9bd5',
'lineColor': '#888',
'actorMargin': 40,
'noteBkgColor': '#0056b3',
'noteTextColor': '#ffffff',
'noteBorderColor': '#004a99'
}
}}%%
sequenceDiagram
participant User as 用户
participant MServer as 商户服务端
participant PMServer as PayerMax 服务端
%% 交易查询流程
MServer->>PMServer: 1.1 交易查询
PMServer-->>MServer: 1.2 返回状态及子状态
MServer-->>User: 1.3 更新提款进展
3. 接口列表
推荐的集成API列表与用途概览如下：
| API名称 | 集成必要性 | 地址 | 用途说明 |
|---|---|---|---|
| 付款要素校验 | 可选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentFieldValidation | 用于在实际发起付款前，对商户提供的收款人要素字段（如账户、姓名、证件等）进行结构化校验，确保发起交易时，收款人信息符合格式规则 |
| 发起付款 | 必选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderPay | 单笔资金支付，适用于用户即时提现或大批量向各地不同收款人付款 |
| 付款查询 | 可选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry | 查询每笔交易的状态 |
| 付款结果通知 | 必选 | https://pay-gate-uat.payermax.com/disbursementResultNotifyUrl | 当支付成功、失败或退票后，PayerMax 主动通知商户 |
| 批量查询付款订单 | 可选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderBatchQry | 分页查询指定时间段内的付款订单明细 |
4. 集成步骤
4.1 出款要素校验
请参考开始API集成-付款要素校验。
4.2 申请付款
- 在出款前需参考API文档中的付款要素，根据要素要求来向您的收款人收集信息，请参考开始API集成-发起付款；详细的接口参数可参考申请付款 API。
注意：
请按照PayerMax提供的格式规则来校验用户填写的信息，避免在交易发起时因为数据格式不符合要求而被拦截；
商户提交付款请求时，上送的订单号需要保证唯一性。PayerMax如果识别出商户使用相同的订单号请求，会返回错误码ORDER_REPEAT。
申请付款后，可能会因为字段格式不符合要求、支付方式合约未开通、填写金额超出支持范围等原因，直接收到失败响应。
通过API发起的付款不可撤销，一旦发起就不能撤回。
4.3 出款查询/回调
- 当PayerMax正常受理您的付款请求后，通过查询API或回调通知两种形式均可感知到付款状态。请参考开始API集成-获取付款状态进行对接。
5. 测试上线
关于付款服务的结果模拟及测试用例，详情请参考全球付款-集成测试。