接口说明
1. 通讯协议
商户接入PayerMax 服务,调用API须遵循以下规则:
类型 | 说明 |
---|---|
传输方式 | 为保证交易安全性,采用HTTPS传输,且TLS版本不低于1.2,详情参考 TLS升级说明 |
提交方式 | 采用POST方法提交 |
数据格式 | 提交和返回数据都为application/json格式 |
字符编码 | 统一采用UTF-8字符编码 |
签名算法 | SHA256WithRSA |
签名要求 | 请求和接收数据均需要校验签名,详细方法请参考 配置与签名 |
判断逻辑 | 先判断协议字段返回,再判断业务返回,最后判断交易状态 |
2. 报文结构
2.1 HTTP请求
json
# HTTP URL
POST https://pay-gate.payermax.com/aggregate-pay/api/gateway/{接口PATH}
# HTTP Header
Accept: application/json
Content-Type: application/json
Content-Length: 580
sign: 使用商户私钥对HTTP Body加签后的签名字符串
# HTTP Body
{
"version": "1.4", # PayerMax版本
"keyVersion": "1", # 密钥版本
"requestTime": "2022-01-17T08:04:13.879+00:00", # 请求时间戳,须在当前时间两分钟内。格式遵循rfc3339规范,格式:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
"appId": "3b242b56a8b64274bcc37dac281120e3",
"merchantNo": "020213827212251",
"data": <业务数据对象JSON>
}
2.1 HTTP响应
json
{
"code": "APPLY_SUCCESS", # 响应结果码,标识请求的处理结果,在失败时,通过结果码可以判定失败原因
"msg": " Success", # 响应结果信息,请求失败时,描述失败原因
"data": <业务数据JSON>
}
注意:
code
仅表示请求处理结果,不表示业务单据状态(如:支付结果、退款结果等)。如果要看业务单据状态,一般可以通过data.status
或data.<其他字段>
获取。
3. 请求地址:
联调环境 | 请求地址 |
---|---|
Test | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway |
Prod | https://pay-gate.payermax.com/aggregate-pay/api/gateway |
4. 接口列表
产品 | 集成模式 | 接口名称 | Endpoint | 描述 |
收款 | 收银台支付 | 下单 | /orderAndPay | 使用payermax收银台进行支付 |
交易查询 | /orderQuery | |||
下单异步通知 | 通知 | |||
退款申请 | /refund | |||
退款查询 | /refundQuery | |||
退款结果通知 | 通知 | |||
纯API支付 | 下单 | /orderAndPay | 使用商户自己收银台进行支付 | |
交易查询 | /orderQuery | |||
下单异步通知 | 通知 | |||
退款申请 | /refund | |||
退款查询 | /refundQuery | |||
退款结果通知 | 通知 | |||
Tokenization支付 | paymentTokenID查询 | /inquirePaymentToken | 当用户使用卡支付方式,支付成功后会把卡token给商户,后续商户发起支付带上卡token进行支付,方便用户快速完成支付 | |
paymentTokenID解绑 | /removePaymentToken | |||
异步通知 | 通知 | |||
PayByLink支付 | 创建支付链接 | /createPaybylink | 直接帮商家创建一个支付链接,发送给消费者后进行支付 | |
查询链接详情 | /queryPaybylink | |||
失效支付链接 | /expirePaybylink | |||
更新异步回调 | 通知 | |||
争议 | 争议异步通知 | 通知 | 交易完成后用户进行拒付、争议、欺诈、投诉等产生的订单通知给商户 | |
案件回复 | /caseReplay | |||
案件查询 | /caseSearch | |||
付款 | API付款 | 付款请求 | /paymentOrderPay | 商户向用户进行付款 |
付款交易查询 | /paymentOrderQry | |||
异步通知 | 通知 | |||
账户余额 | 余额查询 | 实时余额查询 | /currentBalanceQuery | 商户进行余额查询 |
日终余额查询 | /dayEndBalanceQuery |
5. 接口传参规则
是否必填 | 描述 |
---|---|
M | 必填(Mandatory) |
O | 选填(Optional) |
C | 特定条件下必填(Condition) |