Integration Guide
1. Overall process
Any questions you have about the integration process can be directed to Submit Work Orderand PayerMax will contact you as soon as possible.
2. Environmental Information
Test Environment:https://
pay-gate-uat.payermax.com
/aggregate-pay/api/gateway/<Interface PATH>
Integrated Environment:https://
pay-gate.payermax.com
/aggregate-pay/api/gateway/<Interface PATH>
3. Pre-preparation
3.1 Business Negotiation
Through the Contact Uspage of PayerMax official website, you can send your intention to cooperate with us, and communicate with our commercial staff in the early stage; determine the mode of cooperation and select the services and products you need to access.
At the same time, PayerMax commercial staff will create a coordination and docking group to carry out technical docking.
3.2 Register as a Developer
Visit the PayerMax Developer Centerand register as a developer using your email address.
3.3 Get the merchant number and AppId for the test environment
Log in to PayerMax Developer Center with your registered account information and go to merchantNo
)和appId
。
merchantNo
and appId
are required information for a PayerMax interface request, and the following is a sample interface request which indicates the use of both.
curl --request POST \
--url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
--data '{
"version": "1.4",
"keyVersion": "1",
"requestTime": "2025-05-14T06:29:50.085+00:00",
"appId": "<Your merchantNo>",
"merchantNo": "<Your merchantNo>",
"data": <Request Data JSON>
}'
3.4 Configure integration information for the test environment
3.4.1 Configure key information for the test environment
In order to secure network communication, PayerMax uses asymmetric key pairs to countersign and verify communication messages, and the signature uses the SHA256WithRSA signature algorithm. You can check how to generate key pairs and use one of the methods to generate key pairs.
After generating your own key pairs (public and secret), login to PayerMax Developer Center, go to → → , select the created test merchant and click on the , view the PayerMax public key and upload the merchant public key.
Please keep your key information in a safe place. If you accidentally leak your key, please log in to the Developer Center and update your key in a timely manner.
::: warning: Keys are differentiated between test and production environments, so when you finish the integration and release it, you need to configure the key for the production environment, see【配置生产环境的密钥信息】。 :::
3.4.2 Configure the callback address for the test environment
The callback address is used to receive the results of an order asynchronous callback sent from PayerMax, for example:【支付结果回调通知】、【退款结果回调通知等】。
Login to PayerMax Developer Center, go to → → , to set up.
3.5 Setting up a whitelist of server IPs for the test environment
If the network environment of your integration test has a whitelist security restriction on accessing IPs, then please contact PayerMax technical support to get the PayerMax server IP and add it to the whitelist. Otherwise, PayerMax can't launch calls through your【配置的回调地址】normally.
3.6 Open integrated payment methods
Login to PayerMax Developer Center, go to → , you can enable or disable the payment methods available for the current account.
4. Technology Integration
Depending on the merchant's access capabilities, PayerMax provides the following integration documentation.
PayerMax Products | Integrated Mode | |
Global Acquiring | Standard Acquiring | 【收银台】 |
【纯API】 | ||
【前置组件】 | ||
【链接支付】 | ||
Subscription and Auto Debit | 【收银台】 | |
【纯API】 | ||
【前置组件】 | ||
【链接支付】 | ||
Global Payment | Global Payment | 【API付款】 |
【商户服务平台付款】 | ||
Global Collection | Local Collection | / |
Under Standard Acquiring, if you are only concerned with the integration of a particular payment method, you can also view the【按支付方式集成】。
5. Test and Verify
5.1 Check Payment Method Status
Login to PayerMax Developer Center, go to → ,check to see if the payment method you want to test is already enabled. If it is not enabled, you can enable it first and then initiate the test.
5.2 Initiate Connectivity Test
Merchants can first construct a simple request to verify network connectivity and confirm that non-functional configurations such as countersign verification, network whitelisting, etc. have been set up correctly.
5.3 Launching Functionality Test
Once the connectivity test is complete, initiate a success ticket and a failure ticket in the test environment and verify that the request response is as expected.
6. Integration Acceptance
After you have completed the test, you can submit the order number and the merchant number of the production environment by clicking on the “Inquiry Center” icon in the lower right corner of the MMC, and the PayerMax technical support will carry out the necessary calibration. We will check the execution of your test and after passing it, we will put the merchant number of the production environment into the available status.
7. Launch
7.1 Activate Merchant Platform Accounts
After confirming the business cooperation between the two parties, PayerMax will create an administrator account for merchants to log into the MMC based on the “Administrator Account Information” entered in the Merchant Access Application Form. Please check the activation email from PayerMax and follow the instructions to activate the administrator account. The first time you log in, you will need to set a password, so please make sure it is secure to prevent leakage.
7.2 Get the merchant number and AppId for the production environment
Login to MMC,and go to → → to view the merchant number and appId of the production environment.
For more MMCinstructions,such as adding operators, etc., see【此处】。
7.3 Configuring integration information for production environments
7.3.1 Configure key information for the production environment
Log in to MMC,go to → → ,to set the key for the production environment.
7.3.2 Configure the callback address for the production environment
Log in to MMC,go to → → ,to set the key for the production environment.
7.4 Setting up server IP whitelisting for production environments
If the network environment of your production test has a whitelist security restriction on the access IP, then please contact PayerMax technical support to get the PayerMax server IP and add it to the whitelist. Otherwise, PayerMax can't launch the call through your【配置的回调地址】normally.
If accessing a payment product, please contact PayerMax technical support to submit the export IP of your server to us and we will add it to the PayerMax whitelist.
7.5 Open integrated payment methods
For some payment methods, PayerMax needs to report to the payment channel side instead of the merchant, and the transaction can only be uploaded after the report is approved. While waiting for the report to be approved, the merchant is unable to open volume.
You can login to MMCto check the availability status of your payment method.