# API付款 ## 1. 集成准备 + [注册开发者中心账号](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-2-注册成为开发者)； + [上传测试商户公钥](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-1-配置测试环境的密钥信息)，获取平台公钥、AppID、测试商户号等集成信息； + [配置回调地址（WebHook）](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-2-配置测试环境的回调地址)，包括支付结果回调地址、退款结果回调地址等； + [设置测试环境服务器IP白名单](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-5-设置测试环境的服务器ip白名单)； + [配置并开通相应支付方式](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-6-开通集成的支付方式)； + [查看不同环境的请求地址](https://docs.payermax.com/202606-version/developer/integration-guide.md#_2-环境信息)； + [理解请求报文加签和验签的原理](https://docs.payermax.com/202606-version/developer/config-settings.md)，用于生成每次HTTP请求Header的`sign`签名字符串。 ## 2. 交互流程 ### 2.1 付款-成功下单 ```mermaid %%{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 付款-下单失败 ```mermaid %%{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 交易状态查询 ```mermaid %%{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://docs.payermax.com/202606-version/disbursement/element-verification.md) | 可选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentFieldValidation | 用于在实际发起付款前，对商户提供的收款人要素字段（如账户、姓名、证件等）进行结构化校验，确保发起交易时，收款人信息符合格式规则 | | [发起付款](https://docs.payermax.com/202606-version/disbursement/request/api-request.md) | 必选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderPay | 单笔资金支付，适用于用户即时提现或大批量向各地不同收款人付款 | | [付款查询](https://docs.payermax.com/202606-version/appendix/disbursement/transaction-status.md#_1-付款查询接口) | 可选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry | 查询每笔交易的状态 | | [付款结果通知](doc-center/appendix/disbursement/transaction-status.html#_2-付款结果回调通知) | 必选 | https://pay-gate-uat.payermax.com/disbursementResultNotifyUrl | 当支付成功、失败或退票后，PayerMax 主动通知商户 | | [批量查询付款订单](https://docs.payermax.com/202606-version/disbursement/inquiry.md) | 可选 | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderBatchQry | 分页查询指定时间段内的付款订单明细 | ## 4. 集成步骤 ### 4.1 出款要素校验 请参考[开始API集成-付款要素校验](https://docs.payermax.com/202606-version/disbursement/element-verification.md)。 ### 4.2 申请付款 - 在出款前需参考API文档中的付款要素，根据要素要求来向您的收款人收集信息，请参考[开始API集成-发起付款](https://docs.payermax.com/202606-version/disbursement/request/api-request.md)；详细的接口参数可参考[申请付款 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentOrderPay/post)。 ::: warning 注意： 请按照PayerMax提供的格式规则来校验用户填写的信息，避免在交易发起时因为数据格式不符合要求而被拦截； 商户提交付款请求时，上送的订单号需要保证唯一性。PayerMax如果识别出商户使用相同的订单号请求，会返回错误码ORDER_REPEAT。 ::: - 申请付款后，可能会因为字段格式不符合要求、支付方式合约未开通、填写金额超出支持范围等原因，直接收到失败响应。 - 通过API发起的付款不可撤销，一旦发起就不能撤回。 ### 4.3 出款查询/回调 - 当PayerMax正常受理您的付款请求后，通过查询API或回调通知两种形式均可感知到付款状态。请参考[开始API集成-获取付款状态](https://docs.payermax.com/202606-version/appendix/disbursement/transaction-status.md)进行对接。 ## 5. 测试上线 关于付款服务的结果模拟及测试用例，详情请参考[全球付款-集成测试](https://docs.payermax.com/202606-version/disbursement/test-cases.md)。