Integration Guide
1. Overall process
Any questions you have about the integration process can be directed to Submit Ticket and 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 appId>",
"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.
Note:
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 Configure key information for the production environment
.
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:Payment Result Notification and Notification of refund results.
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 callback address 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 | Integration Docs | ||
Global Acquiring | Acquiring Basic Products | Cashier Payment | |
Direct API Payment | |||
Drop In Payment | |||
Pay By Link | |||
Subscription and Auto Debit | Subscription | Cashier Payment | |
Direct API Payment | |||
Drop In Payment | |||
Auto Debit | Cashier Payment | ||
Direct API Payment | |||
Drop In Payment | |||
Global Payout | Global Payout | API Payout | |
MMC Batch Payout, MMC Single Payout | |||
Global Collection | Local Bank Collection | Local Bank Collection Process |
Under Standard Acquiring, if you are only concerned with the integration of a particular payment method, you can also view the Acquiring Product Integration - Acquiring Basic Products.
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 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.
in the lower right corner of the7. 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 MMC instructions,such as adding operators, etc., see Merchant Platform Introduction.
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 callback address 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 MMC to check the availability status of your payment method.