API付款
1. 集成准备
上传测试商户公钥,获取平台公钥、AppID、测试商户号等集成信息;
配置回调地址(WebHook),包括支付结果回调地址、退款结果回调地址等;
理解请求报文加签和验签的原理,用于生成每次HTTP请求Header的
sign
签名字符串。
2. 交互流程
2.1 付款-成功下单
2.2 付款-下单失败
2.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 测试上线
5.1 结果模拟
对于付款不同支付结果的处理流程,PayerMax 付款API提供了根据交易金额(amount)模拟不同状态支付结果的功能,具体规则如下:
失败:可选择设置固定金额(本币):110、11000;
支付中:可选择设置固定金额(本币):100、10000;
成功:可选择设置固定金额(本币):其他金额。
特别提醒:
- 若您的交易金额币种不能为本币,仍希望模拟成功、失败的交易,请填写remark字段,remark=SUCCESS,模拟交易成功;remark=FAILED,模拟交易失败;remark=BOUNCEBACK,模拟交易退票。
remark和交易金额同时满足模拟条件时,以remark为准。例如:remark=SUCCESS,交易金额=811,结果返回成功。 - 若您测试埃及Fawry出款,下单传了notifyEmail,希望收到取款码邮件,请参考上面支付中的本币金额下单。
5.2 测试用例
在完成产品能力接入后,为了帮助商户验证付款服务功能正确性以及了解各接口的功能和预期行为,PayMax为开发人员提供了完善的测试用例。您可以根据实际对接情况按需下载:API单笔出款测试用例。