Pre-integration Preparation

This document describes the pre-connection preparation requirements, helping partners efficiently understand the preparation steps before access and smoothly complete subsequent system integration.

1. Overall Process

graph LR
    direction LR

    %% Style Definitions
    %% 1. Subgraph border: Blue border with light background
    classDef subStyle fill:#ebf5ff,stroke:#01579b,stroke-width:1px;
    %% 2. Blue node style
    classDef blueNode fill:#0056b3,stroke:#4169E1,stroke-width:2px,color:#ffffff,font-weight:bold;
    %% 3. Invisible title style: No border, no background, bold blue text
    classDef titleStyle fill:none,stroke:none,color:#01579b,font-weight:bold,font-size:16px;

    subgraph S1 [ ]
        direction TB
        t1[Business Negotiation] ~~~ n1_1[Business Communication] --> n1_2[Activate Merchant Platform]
    end

    subgraph S2 [ ]
        direction TB
        t2[Integration Preparation] ~~~ n2_1[Register Developer Center] --> n2_2[Configure Test Integration Info]
    end

    subgraph S3 [ ]
        direction TB
        t3[Technical Integration] ~~~ n3_1[Review Documentation] --> n3_3[Technical Development]
    end

    subgraph S4 [ ]
        direction TB
        t4[Integration Testing] ~~~ n4_1[Enable Sandbox Payment Methods]
        n4_1 --> n4_2[Initiate Payment Test Flow]
    end

    subgraph S5 [ ]
        direction TB
        t5[UAT & Acceptance] ~~~ n5_1[Submit Test Information]
        n5_1 --> n5_2[Check Test Orders & Logs]
    end

    subgraph S6 [ ]
        direction TB
        t6[Go-Live] ~~~ n6_1[Configure Production Environment]
        n6_1 --> n6_2[Enable Live Payment Methods]
    end

    %% Connection Logic
    S1 --> S2 --> S3 --> S4 --> S5 --> S6

    %% Apply Styles
    class S1,S2,S3,S4,S5,S6 subStyle;
    class n1_1,n1_2,n2_1,n2_2,n3_1,n3_3,n4_1,n4_2,n5_1,n5_2,n6_1,n6_2 blueNode;
    class t1,t2,t3,t4,t5,t6 titleStyle;

Any questions you have about the integration process can be directed to Submit Ticket and PayerMax will contact you as soon as possible.

2. Register as a Developer

2.1 Email Registration

Visit the PayerMax Developer Center and register as a developer using your email address.

1. Open the login & registration page and click Register

1. Complete email registration and verification

2.2 Test Parameter Description

Log in to PayerMax Developer Center with the registered account, go to BaseSetup → Develop Info to view the automatically generated test environment development parameters.

Member ID, Merchant ID, appId: A set of parameters automatically generated by the system for developer test environment use, required for PayerMax API requests;
Key Type: RSA;
Public Key Upload: Developers need to upload the merchant public key to PayerMax for verifying merchant signatures. Refer to 3.2 Key Description & Configuration for public and private key instructions;
Invite Collaborators: Invited collaborators share the same merchant ID in the developer platform;
Bind Production Merchant ID: Complete self-acceptance by binding a production merchant ID, so that you can obtain development parameters corresponding to the production merchant ID in the merchant platform. (Binding the official merchant ID requires the production merchant ID administrator Assign operator permissions )

3. Parameter Configuration & Description

3.1 Configure Async Notification Callback URL

The callback address is used for the access party's server to receive asynchronous order callback results from PayerMax server. The address can be submitted via corresponding API request parameters or configured in the merchant admin platform. API-submitted callback address takes priority over the one configured in the merchant platform.

Test Environment (Developer Platform): Developer Platform → BaseSetup → Develop Info → Notify URL

3.2 Key Description and Configuration

3.2.1 Key Introduction

Encryption Algorithm: RSA

Key Format: PKCS8, remove header, footer and line breaks

Signature Algorithm: SHA256WithRSA

Key Length: 2048 bits

Note: Please properly keep your key information. Update the key promptly if it is accidentally leaked.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#fcf4e4',
    'noteTextColor': '#00000',
    'noteBorderColor': '#FAECCC'
  }
}}%%
sequenceDiagram
    participant Merchant as Merchant
    participant Platform as PayerMax

    rect rgb(235, 245, 255)
        Note over Merchant: Holds: Merchant Private Key, PayerMax Public Key
        Note over Platform: Holds: Merchant Public Key, PayerMax Private Key
    end

    Merchant->>Platform: 1. Sign the body using "Merchant Private Key" and send request to PayerMax
    Platform->>Platform: 2. PayerMax verifies the signature using "Merchant Public Key"
    
    Platform->>Merchant: 3. PayerMax signs the callback data with "PayerMax Private Key" and sends it to the Merchant
    Merchant->>Merchant: 4. Merchant verifies the signature using "PayerMax Public Key"

3.2.2 Key Generation (Skip this step if you already have keys)

Merchant public and private key pairs can be generated in any one of the following methods (choose only one). Please keep the generated Merchant Private Key properly by yourself, which is used to sign request messages sent to PayerMax. Upload the Merchant Public Key to PayerMax via the Merchant Dashboard for merchant signature verification and preventing message tampering during network transmission. Meanwhile, obtain the PayerMax Public Key from the platform and integrate it into your own program to verify the signature of messages signed by PayerMax.

Quick Online Key Pair Generation

Click PayerMax Key Generation Tool to generate a key pair quickly.

Generate via OpenSSL

Generate PEM format public and private key files using OpenSSL commands, then manually remove the header, footer and line breaks to obtain the pure key content.

Download and install OpenSSL, refer to official documentation: https://www.openssl.org/source/

Execute the following commands:

# private key
openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out private.key.pem
# public key
openssl rsa -in private.key.pem -pubout > public.key.pem

After executing the above command, two files will be generated as follows (example):

File public.key.pem-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzN6tx98b4KZB1uqEuT7P
/nWHrYqFdiy+Kzs9KZ6JtSQWb3b45loOsdUxFeaCAt+ZJ0+fNJRDnwc7AiKOlgbw
0HT93WRVZXP6cwQV1Bg1XybBxtQE4OcEq+Uzzmd7RoBkQuNmjIUgDYtWPBSekSpZ
AhWkk4dh8Nd7Qv2BvJNNOISVFcROFgMgbGz80v6WofR4nnTEdTB+j4pR/Q4dhnIR
OlaWrai+hBPn95sahQ+Ujf7LZgLyhpyQeS+/xsLv29lDI6D+8neR1tsOYdOp8f8Q
NwDkOroMlzxkQeYsJDLpLG8p58zHSdcLOsopVe2u41uzdrQ8qjhw4FU9eBOmFite
iwIDAQAB

File private.key.pem-----BEGIN PRIVATE KEY-----
MIIEwAIBADANBgkqhkiG9w0BAQEFAASCBKowggSmAgEAAoIBAQDM3q3H3xvgpkHW
6oS5Ps/+dYetioV2LL4rOz0pnom1JBZvdvjmWg6x1TEV5oIC35knT580lEOfBzsC
Io6WBvDQdP3dZFVlc/pzBBXUGDVfJsHG1ATg5wSr5TPOZ3tGgGRC42aMhSANi1Y8
FJ6RKlkCFaSTh2Hw13tC/YG8k004hJUVxE4WAyBsbPzS/pah9HiedMR1MH6PilH9
Dh2GchE6VpatqL6EE+f3mxqFD5SN/stmAvKGnJB5L7/Gwu/b2UMjoP7yd5HW2w5h
06nx/xA3AOQ6ugyXPGRB5iwkMuksbynnzMdJ1ws6yilV7a7jW7N2tDyqOHDgVT14
E6YWK16LAgMBAAECggEBAKFLC8yZdixHGPzohHgH4N94jsptjae9kDcfG4dB3y8y
60r0gv9wlbMiotOYOHGkssKFaFWQCTESEz4aEOJDMqMcCKaeELGgPuUAqWLjcFmq
fNNaJ0EeAMqI2GG/jQmzmbwjpqApS1P+iHUi0rh9e7gta/YOl2hzbgMO7W6XFivQ
pMIQZQE0WpmpK8cNgev/Xog8ZnHFC6XGUgK+mDVvJMYwmywUPIfLw2fvAZ29Qogt
qiGeFCJSwAL1VkxryXSjJJBKuoc3cXEcq/hjhz6G9rvd50Lj2kCWMd8iqm/dtFyh
DnT5WSFYNPIH0Up9qtqeP+TqgI/SrztAVHgUXVB2ABkCgYEA9cSeHG04Pj3p9ZCe
Cc6qb6L2kFphb62BhmUSHZ50p6X1KsSMw4wnzbrgrvcSe97iWZNLC536eQVHE5gL
4ZjIxylYkp+FuuPHMIDseASR2pNmY2sJ83iTB4C9Y+37+64wBceFiXWBERdJA1t2
MnzWLR8ijFfmHQ4KX3DJOhR05qUCgYEA1WYroahttPyvMFHdmcCphF9jhF3U6SGu
VndwTtqaGLHzCmSvHxLFyd8ziw/F344IGIn8fIbOqhFAijyliD53kGMiKSUqMH4Q
eP2RfxGrZqek3f6pvyUtxfjXAh6+7pfL46u0AzmyvcpaGXqQToecCF43MCdbxh7Z
3CViGfBcWW8CgYEAvJRcufU4ddHuJoYMLfxNHRIPXV5sa1PYEjaVevKuEkGuaF2e
oSF3HU4qvzZIEZJJXnA94jEbEydwjWFapIUmcmOQWhlbdLb4jYgvajwfanc11k04
uoAnWVd4eygN9OWIZbbeCUaHfYS/ensAq+bMNJ0yVjvQDzVJ0kfpr84okR0CgYEA
mBroNKTx9ZQ6Zu2jT2lVKuY27+1VygpY0ob1xS7psXp9asYTUMm3s0ll2tQWTV9W
g+8uya/o9K2xXBcYQgGMhZ0zhzJXXRMuOJ88qt70VgpeaGGRqo4cj0TsNDWoEDag
fJoxiC8DKWZnTEvhOihM3mYRXkBfmNr6nIEE6Mo7eP8CgYEA8KqzIk+5On3xmeES
fQcLPYiaO9Hlttc7flyIpUL52Og7S1T/ekdiBVIDlePpjRx5H0iCtANyWmQq0Xbf
SseQ9SFJ/4DLvDMawhvolmxHs98PNa8xZ9KdXgUNc7RcewUVhK2aLkxUQKNO0lww
GGDGWfvePWzlVotJd0bM+a/X4qg=

3.2.3 Key Configuration

After the merchant generates the public and private key pair, upload the public key via the merchant management platform, and download the PayerMax public key at the same time.

Upload Test Merchant Public Key: Log in to the Developer Platform, go to BaseSetup → Develop Info → Secret Info → Upload PublicKey.

Download Platform Public Key:

3.2.4 Signing and Verification Instructions

Merchant Signing

Recommendation: Serialize content into a string → sign with this string → send directly as the request Body
Prohibited Operation: Sign the object directly and then reserialize it through the framework for delivery. Differences in field order or empty fields will cause signature verification failure.

WARNING

Notes on signature format:

The message string signed with the merchant private key must be exactly the same as the raw string in the HTTP Body; otherwise, PayerMax signature verification will fail. For example, the following two JSON contents are semantically identical, but their signature results are different due to formatting differences.
You can use the developer Self-service Signing Tool to test the signing process.

Formatted JSON string:

json

{
    "key1":"val1",
    "key2": "val2",
    "key3": "val3"
}

Sign the result using the example private key：
"FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Compressed json string:

json

{"key1":"val1","key2":"val2","key3":"val3"}

Sign the result using the example private key：
"W/unZQUH9366PZDhYlCghA7q66VmPDBN/7OvVKhigQNfLJPxGnbhrH6JV4rYlsyfduPt4QKZalaafvs/tJ+CVOr2RGt3815hcAPB7MN/u4y3W+IfbwTXkT7gWujT652YDfMls2dwRCYun++DSOVFHkP8FUp8/Rb6e8CuKbA40RwfHfUTek24TMq0JmiYZDfRYbMUE30Pm8PXDAStoTTOqjJ+5zVAMWCzUwId1/P3iNWue+DUwCyLEA6tHFIJX8dUoSlbtjRs1p4Q8ahSFg5Dx+RORtLclnp8g38hgWFNsvcSuW3RXTkwIYmmbp5Qguw16af9P8Li82zI4M8TqgI08g=="

Merchant Signature Verification

Merchants must use the PayerMax public key for signature verification;
Verification must be performed with the original HTTP Body. Do not use deserialized objects for verification;

Platform upgrades may add or remove certain fields. Deserialization by development frameworks may omit empty or unknown fields, leading to signature verification failures.

4. Set Server IP Whitelist

If your network environment for integration testing adopts IP whitelist access restrictions, please submit a ticket as shown below to obtain PayerMax server IPs and add them to your whitelist. Otherwise, PayerMax cannot normally initiate callbacks to your configured callback address.

5. Enable Payment Methods

To enable payment methods in the test environment, log in to the PayerMax Developer Center, navigate to BaseSetup → Payment Method Management, where you can enable or disable payment methods available for the current account.

6. Integration Acceptance

After passing the acceptance check initiated on the Developer Platform, you can configure development parameters for the production environment.

6.1 Initiate Functional Testing

Test Environment：https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <API-PATH>

Please create one successful order and one failed order in the test environment, and verify that requests and responses meet expectations.
Refer to the documents below for request details:

PayerMax Product		Integration Mode	Integration Document
Global Acquiring	Standard Acquiring	Cashier Payment	Cashier-Full Cashier
			Cashier-Specified Payment Method
		Frontend Component	Frontend Component-CARD
			Frontend Component-ApplePay
			Frontend Component-GooglePay
		Direct API	Direct API-CARD
			Direct API-GooglePay
			Direct API-ApplePay
			Direct API-APM
	Subscription and Auto Debit	/	PayerMax Manage Subscription Plans
			Merchant Managed Subscription Plans
			Non-Periodic Auto Debit
Global Payout	Global Payout	API Payout	API Payout
		Platform Payout	Merchant Platform Batch Payout , Merchant Platform Single Payout
Global Collection	Local Collection	/	Local Collection Process

Integration Modes Details

Acquiring Basic Products

CARD

GOOGLEPAY

APPLEPAY

Subscription and Auto Debit

PayerMax Manage Subscription Plans

Merchants Manage Subscription Plans

Non-Periodic Auto Debit

Drop In

Tokenization

Auth-Capture

ChargeBack

Risk Control

Troubleshooting

Payment Method Classification

Payment Method Details

Asia Pacific

Central Asia

Middle East and Africa

Europe

North America and Latin America

Global

Pre-integration Preparation ​

1. Overall Process ​

2. Register as a Developer ​

2.1 Email Registration ​

2.2 Test Parameter Description ​

3. Parameter Configuration & Description ​

3.1 Configure Async Notification Callback URL ​

3.2 Key Description and Configuration ​

3.2.1 Key Introduction ​

3.2.2 Key Generation (Skip this step if you already have keys) ​

3.2.3 Key Configuration ​

3.2.4 Signing and Verification Instructions ​

4. Set Server IP Whitelist ​

5. Enable Payment Methods ​

6. Integration Acceptance ​

6.1 Initiate Functional Testing ​

Pre-integration Preparation

1. Overall Process

2. Register as a Developer

2.1 Email Registration

2.2 Test Parameter Description

3. Parameter Configuration & Description

3.1 Configure Async Notification Callback URL

3.2 Key Description and Configuration

3.2.1 Key Introduction

3.2.2 Key Generation (Skip this step if you already have keys)

3.2.3 Key Configuration

3.2.4 Signing and Verification Instructions

4. Set Server IP Whitelist

5. Enable Payment Methods

6. Integration Acceptance

6.1 Initiate Functional Testing