# 接口说明 ## 1. 通讯协议 商户接入PayerMax 服务，调用API须遵循以下规则： | 类型 | 说明 | |------------|------------------------------------------------------------| | 传输方式 | 为保证交易安全性，采用HTTPS传输，且TLS版本不低于1.2，详情参考 [TLS升级说明](/202606-version/developer/tls-upgrade.md) | | 提交方式 | 采用POST方法提交 | | 数据格式 | 提交和返回数据都为application/json格式 | | 字符编码 | 统一采用UTF-8字符编码 | | 签名算法 | SHA256WithRSA | | 签名要求 | 请求和接收数据均需要校验签名，详细方法请参考 [配置与签名](/202606-version/developer/config-settings.md) | | 判断逻辑 | 先判断协议字段返回，再判断业务返回，最后判断交易状态 | ## 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.2 HTTP响应 ```json { "code": "APPLY_SUCCESS", # 响应结果码，标识请求的处理结果，在失败时，通过结果码可以判定失败原因 "msg": " Success", # 响应结果信息，请求失败时，描述失败原因 "data": <业务数据JSON> } ``` ::: warning 注意： `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](https://docs.payermax.com/202606-version/receipt/cashier/api-integration.md) | | | | | 交易查询 | [/orderQuery](https://docs.payermax.com/202606-version/receipt/transaction-inquiry.md) | | | | 收银台支付 | 下单异步通知 | [通知](https://docs.payermax.com/202606-version/receipt/result-notifications/callback-notification.md) | 使用payermax收银台进行支付 | | | | 退款申请 | [/refund](https://docs.payermax.com/202606-version/receipt/refund/refund-doc.md#_4-退款申请) | | | | | 退款查询 | [/refundQuery](https://docs.payermax.com/202606-version/receipt/refund/refund-doc.md#_3-退款查询) | | | | | 退款结果通知 | [通知](https://docs.payermax.com/202606-version/receipt/refund/refund-doc.md#_5-退款结果通知) | | | | | 下单 | [/orderAndPay](https://docs.payermax.com/202606-version/receipt/direct-api/api-integration.md) | | | | | 交易查询 | [/orderQuery](https://docs.payermax.com/202606-version/receipt/transaction-inquiry.md) | | | | 纯API支付 | 下单异步通知 | [通知](https://docs.payermax.com/202606-version/receipt/result-notifications/callback-notification.md) | 使用商户自己收银台进行支付 | | | | 退款申请 | [/refund](https://docs.payermax.com/202606-version/receipt/refund/refund-doc.md#_4-退款申请) | | | 收款 | | 退款查询 | [/refundQuery](https://docs.payermax.com/202606-version/receipt/refund/refund-doc.md#_3-退款查询) | | | | | 退款结果通知 | [通知](https://docs.payermax.com/202606-version/receipt/refund/refund-doc.md#_5-退款结果通知) | | | | | paymentTokenID查询 | [/inquirePaymentToken](https://docs.payermax.com/202606-version/receipt/tokenization/inquire.md) | | | | Tokenization支付 | paymentTokenID解绑 | [/removePaymentToken](https://docs.payermax.com/202606-version/receipt/tokenization/remove.md) | 当用户使用卡支付方式，支付成功后会把卡token给商户，后续商户发起支付带上卡token进行支付，方便用户快速完成支付 | | | | 异步通知 | [通知](https://docs.payermax.com/202606-version/receipt/tokenization/notify.md) | | | | | 创建支付链接 | [/createPaybylink](https://docs.payermax.com/202606-version/receipt/pay-by-link/create.md) | | | | PayByLink支付 | 查询链接详情 | [/queryPaybylink](https://docs.payermax.com/202606-version/receipt/pay-by-link/inquiry.md) | 直接帮商家创建一个支付链接，发送给消费者后进行支付 | | | | 失效支付链接 | [/expirePaybylink](https://docs.payermax.com/202606-version/receipt/pay-by-link/expired.md) | | | | | 更新异步回调 | [通知](https://docs.payermax.com/202606-version/receipt/pay-by-link/updates.md) | | | | | 争议异步通知 | [通知](https://docs.payermax.com/202606-version/receipt/chargeback/backend-notification.md) | | | | 争议 | 案件回复 | [/caseReplay](https://docs.payermax.com/202606-version/receipt/chargeback/retrieval-response.md) | 交易完成后用户进行拒付、争议、欺诈、投诉等产生的订单通知给商户 | | | | 案件查询 | [/caseSearch](https://docs.payermax.com/202606-version/receipt/chargeback/inquiry.md) | | | | | 付款请求 | [/paymentOrderPay](https://docs.payermax.com/202606-version/disbursement/request/api-request.md) | | | 付款 | API付款 | 付款交易查询 | [/paymentOrderQry](https://docs.payermax.com/202606-version/disbursement/inquiry.md) | 商户向用户进行付款 | | | | 异步通知 | [通知](https://docs.payermax.com/202606-version/disbursement/notices.md) | | | 账户余额 | 余额查询 | 实时余额查询 | [/currentBalanceQuery](https://docs.payermax.com/202606-version/mmc/multi-currency-fund/balance-inquiry.md) | 商户进行余额查询 | | | | 日终余额查询 | [/dayEndBalanceQuery](https://docs.payermax.com/202606-version/mmc/multi-currency-fund/balance-inquiry.md) | | ## 5. 接口传参规则 | 是否必填 | 描述 | |------|--------------------| | M | 必填（Mandatory） | | O | 选填（Optional） | | C | 特定条件下必填（Condition） |