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
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
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

# 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": <Business data object JSON>
}

2.1 HTTP Response

{
  "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": <Business data object JSON>
}

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.<other fields>.

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
Receipt	Cashier Payment	Place an Order	/orderAndPay	Use PayerMax cashier for payment
		Transaction Inquiry	/orderQuery
		Order Asynchronous Notification	/notification
		Refund Application	/refund
		Refund Inquiry	/refundQuery
		Refund Asynchronous Notification	/notification
	Pure API Payment	Place an Order	/orderAndPay	Use merchant's own cashier for payment
		Transaction Inquiry	/orderQuery
		Order Asynchronous Notification	/notification
		Refund Application	/refund
		Refund Inquiry	/refundQuery
		Refund Asynchronous Notification	/notification
	Tokenization Payment	PaymentTokenID Inquiry	/inquirePaymentToken	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.
		PaymentTokenID Unbinding	/removePaymentToken
		Asynchronous Notification	/notification
	PayByLink Payment	Create Payment Link	/createPaybylink	Directly create a payment link for the merchant, send it to the consumer for payment
		Query Link Details	/queryPaybylink
		Invalid Payment Link	/expirePaybylink
		Update Asynchronous Callback	/notification
	Disputes	Dispute Asynchronous Notification	/notification	Notifications to merchants for orders generated due to chargebacks, disputes, fraud, complaints, etc., after the completion of the transaction
		Case Reply	/caseReplay
		Case Inquiry	/caseSearch
Payment	API Payment	Payment Request	/paymentOrderPay	Merchant makes payment to users
		Payment Transaction Inquiry	/paymentOrderQry
		Asynchronous Notification	/notification
Account Balance	Balance Inquiry	Real-time Balance Inquiry	/currentBalanceQuery	Merchant performs balance inquiry
		Day-end Balance Inquiry	/dayEndBalanceQuery

5. API parameter transfer rules

If required	Description
M	Mandatory
O	Optional
C	Condition