# API Description ## 1. Communication Protocols Merchants accessing the PayerMax service and calling the API must follow the following rules: | type | desc | |-------------------|-----------------------------------------------------------------------------------------------------| | Transmission Method | In order to ensure transaction security, HTTPS transmission is adopted, and TLS version should not be lower than 1.2. For details, please refer to [TLS Upgrade Instructions](https://docs.payermax.com/en/202606-version/developer/tls-upgrade.md) | | Submission Method | Submit by POST method | | Data Format | Submit and return data in application/json format | | Character Encoding | Uniformly use UTF-8 character encoding | | Signature Algorithm| SHA256WithRSA | | Signature Requirements | Both request and received data need to verify the signature. For details, please refer to [Config Settings and Signature Rules](https://docs.payermax.com/en/202606-version/developer/config-settings.md) | | Process Logic | First refer to the return of the protocol field, then refer to the code in the response message, and finally refer to the transaction status | ## 2. Message Structure ### 2.1 HTTP Request ```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: Use the merchant's private key to sign the HTTP Body. # HTTP Body { "version": "1.4", # PayerMax Version "keyVersion": "1", # Key Version "requestTime": "2022-01-17T08:04:13.879+00:00", # Request timestamp, which must be within two minutes of the current time. The format follows the rfc3339 specification, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX "appId": "3b242b56a8b64274bcc37dac281120e3", "merchantNo": "020213827212251", "data": } ``` ### 2.1 HTTP Response ```json { "code": "APPLY_SUCCESS", # The response result code identifies the processing result of the request. In case of failure, the result code can be used to determine the cause of the failure. "msg": " Success", # Response result information, if the request fails, describe the reason for the failure "data": } ``` ::: warning Note: `code` only indicates the request processing result, not the business document status (such as payment result, refund result, etc.). If you want to view the business document status, you can generally obtain it through `data.status` or `data.`. ::: ## 3. Request URL | Environment | Link | | ------ | ------------ | | Test | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway | | Prod | https://pay-gate.payermax.com/aggregate-pay/api/gateway | ## 4. API List | Product | Integration Mode | Interface Name | Endpoint | Description | | --------------- | -------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | Place an Order | [/orderAndPay](https://docs.payermax.com/en/202606-version/receipt/cashier/api-integration.md) | | | | | Transaction Inquiry | [/orderQuery](https://docs.payermax.com/en/202606-version/receipt/transaction-inquiry.md) | | | | Cashier Payment | Order Asynchronous Notification | [/notification](https://docs.payermax.com/en/202606-version/receipt/result-notifications/callback-notification.md) | Use PayerMax cashier for payment | | | | Refund Application | [/refund](https://docs.payermax.com/en/202606-version/receipt/refund/refund-doc.md#_4-refund-application) | | | | | Refund Inquiry | [/refundQuery](https://docs.payermax.com/en/202606-version/receipt/refund/refund-doc.md#_3-refund-inquiry) | | | | | Refund Asynchronous Notification | [/notification](https://docs.payermax.com/en/202606-version/receipt/refund/refund-doc.md#_5-refund-notification) | | | | | Place an Order | [/orderAndPay](https://docs.payermax.com/en/202606-version/receipt/direct-api/api-integration.md) | | | | | Transaction Inquiry | [/orderQuery](https://docs.payermax.com/en/202606-version/receipt/transaction-inquiry.md) | | | | Pure API Payment | Order Asynchronous Notification | [/notification](https://docs.payermax.com/en/202606-version/receipt/refund/refund-doc.md#_5-refund-notification) | Use merchant's own cashier for payment | | | | Refund Application | [/refund](https://docs.payermax.com/en/202606-version/receipt/refund/refund-doc.md#_4-refund-application) | | | Receipt | | Refund Inquiry | [/refundQuery](https://docs.payermax.com/en/202606-version/receipt/refund/refund-doc.md#_3-refund-inquiry) | | | | | Refund Asynchronous Notification | [/notification](https://docs.payermax.com/en/202606-version/receipt/refund/refund-doc.md#_5-refund-notification) | | | | | PaymentTokenID Inquiry | [/inquirePaymentToken](https://docs.payermax.com/en/202606-version/receipt/tokenization/inquire.md) | | | | Tokenization Payment | PaymentTokenID Unbinding | [/removePaymentToken](https://docs.payermax.com/en/202606-version/receipt/tokenization/remove.md) | When users use card payment, after a successful payment, the card token will be given to the merchant. Subsequent payments by the merchant will carry the card token for quick payment completion. | | | | Asynchronous Notification | [/notification](https://docs.payermax.com/en/202606-version/receipt/tokenization/notify.md) | | | | | Create Payment Link | [/createPaybylink](https://docs.payermax.com/en/202606-version/receipt/pay-by-link/create.md) | | | | PayByLink Payment | Query Link Details | [/queryPaybylink](https://docs.payermax.com/en/202606-version/receipt/pay-by-link/inquiry.md) | Directly create a payment link for the merchant, send it to the consumer for payment | | | | Invalid Payment Link | [/expirePaybylink](https://docs.payermax.com/en/202606-version/receipt/pay-by-link/expired.md) | | | | | Update Asynchronous Callback | [/notification](https://docs.payermax.com/en/202606-version/receipt/pay-by-link/updates.md) | | | | | Dispute Asynchronous Notification | [/notification](https://docs.payermax.com/en/202606-version/receipt/chargeback/backend-notification.md) | | | | Disputes | Case Reply | [/caseReplay](https://docs.payermax.com/en/202606-version/receipt/chargeback/retrieval-response.md) | Notifications to merchants for orders generated due to chargebacks, disputes, fraud, complaints, etc., after the completion of the transaction | | | | Case Inquiry | [/caseSearch](https://docs.payermax.com/en/202606-version/receipt/chargeback/inquiry.md) | | | | | Payment Request | [/paymentOrderPay](https://docs.payermax.com/en/202606-version/disbursement/request/api-request.md) | | | Payment | API Payment | Payment Transaction Inquiry | [/paymentOrderQry](https://docs.payermax.com/en/202606-version/disbursement/inquiry.md) | Merchant makes payment to users | | | | Asynchronous Notification | [/notification](https://docs.payermax.com/en/202606-version/disbursement/notices.md) | | | Account Balance | Balance Inquiry | Real-time Balance Inquiry | [/currentBalanceQuery](https://docs.payermax.com/en/202606-version/mmc/multi-currency-fund/balance-inquiry.md) | Merchant performs balance inquiry | | | | Day-end Balance Inquiry | [/dayEndBalanceQuery](https://docs.payermax.com/en/202606-version/mmc/multi-currency-fund/balance-inquiry.md) | | ## 5. API Parameter Transfer Rules | If required | Description | | ------------ | ------------ | | M | Mandatory | | O | Optional | | C | Condition |