API Payout
1. Integration Preparation
Upload test merchant public key，get the platform public key, AppID, test merchant number and other integration information；
Configure the callback address (WebHook), including the payment result callback address, refund result callback address, and so on;
Understand the principles of request message signing and verification, for generating a
signsignature string for each HTTP request Header.
2. Interaction Process
2.1 Payment - Order Successfully Placed
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#e6f0ff',
'primaryTextColor': '#333',
'primaryBorderColor': '#5b9bd5',
'lineColor': '#888',
'actorMargin': 40,
'noteBkgColor': '#0056b3',
'noteTextColor': '#ffffff',
'noteBorderColor': '#004a99'
}
}}%%
sequenceDiagram
participant User as User
participant MServer as Merchant Server
participant PMServer as PayerMax Server
%% 1. Validation Phase
User->>MServer: 1.1 Fill in beneficiary information
MServer->>PMServer: 1.2 Validate payout credentials
PMServer->>PMServer: 1.3 Validate PayerMax
internal field rules
PMServer-->>MServer: 1.4 Return validation results and errors
MServer-->>User: 1.5 Prompt user for corrections
User->>MServer: 1.6 Correct information and submit to save
%% 2. Withdrawal Initiation Phase
User->>MServer: 2.1 Initiate withdrawal
MServer->>PMServer: 2.2 Initiate payout
PMServer->>PMServer: 2.3 Validate and accept payout
%% 3. Result Callback Phase
PMServer->>MServer: 3.1 Callback with final result
MServer->>PMServer: 3.2 Respond with success/acknowledgment
MServer-->>User: 3.3 Return transaction result
2.2 Payment - Order Failed
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#e6f0ff',
'primaryTextColor': '#333',
'primaryBorderColor': '#5b9bd5',
'lineColor': '#888',
'actorMargin': 40,
'noteBkgColor': '#0056b3',
'noteTextColor': '#ffffff',
'noteBorderColor': '#004a99'
}
}}%%
sequenceDiagram
participant User as User
participant MServer as Merchant Server
participant PMServer as PayerMax Server
%% 1. Validation Phase
User->>MServer: 1.1 Fill in beneficiary info
MServer->>PMServer: 1.2 Payout element validation
PMServer->>PMServer: 1.3 Validate PayerMax
internal field rules
PMServer-->>MServer: 1.4 Return validation result and error
MServer-->>User: 1.5 Prompt user to modify
User->>MServer: 1.6 Correct modification, submit and save
%% 2. Withdrawal Initiation Phase
User->>MServer: 2.1 Initiate withdrawal
MServer->>PMServer: 2.2 Initiate payout
PMServer->>PMServer: 2.3 Validate and accept payout
%% 3. Failure Feedback Phase
PMServer->>MServer: 3.1 Failure response
MServer-->>User: 3.2 Return transaction result
2.3 Transaction Status Query
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#e6f0ff',
'primaryTextColor': '#333',
'primaryBorderColor': '#5b9bd5',
'lineColor': '#888',
'actorMargin': 40,
'noteBkgColor': '#0056b3',
'noteTextColor': '#ffffff',
'noteBorderColor': '#004a99'
}
}}%%
sequenceDiagram
participant User as User
participant MServer as Merchant Server
participant PMServer as PayerMax Server
%% Transaction Query Flow
MServer->>PMServer: 1.1 Transaction query
PMServer-->>MServer: 1.2 Return status and sub-status
MServer-->>User: 1.3 Update withdrawal progress
3. Interface List
The recommended integration API list and usage overview are as follows:
| API Name | Integration Necessity | Address | Description of Purpose |
|---|---|---|---|
| Payment Element Validation | Optional | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentFieldValidation | Used to perform structured validation on the payee element fields (such as account number, name, ID, etc.) provided by the merchant before actually initiating payment, ensuring that the payee information complies with formatting rules when initiating the transaction. |
| Initiate Payout | Mandatory | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderPay | Single payment, suitable for instant cash withdrawals or bulk payments to multiple recipients in different locations |
| Payment Inquiry | Optional | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry | Query the status of each transaction |
| Payment Result Notification | Mandatory | https://pay-gate-uat.payermax.com/disbursementResultNotifyUrl | PayerMax proactively notifies merchants when a payment succeeds, fails, or is returned |
| Batch Query Payment Orders | Optional | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderBatchQry | Query payment order details within a specified time period by page. |
4. Integration Steps
4.1 Withdrawal Element Verification
Please refer to API Integration - Payout Element Verification.
4.2 Request Payment
- Before making a payment, please refer to the payment elements in the API documentation and collect information from your payee according to the element requirements, please refer to API Integration - Initiate Payout. For detailed interface parameters, please refer to Disbursement Request API.
Note:
Please verify user-entered information according to the formatting rules provided by PayerMax to avoid interception of transactions due to non-compliant data formats.
When merchants submit payment requests, the order number they submit must be unique. If PayerMax identifies a merchant requesting with the same order number, it will return the error code ORDER_REPEAT.
After applying for payment, you may receive a failure response directly due to reasons such as the field format not meeting the requirements, the payment method contract not being activated, or the amount entered exceeding the supported range.
Payments initiated through the API are irrevocable and cannot be withdrawn once initiated.
4.3 Withdrawal Inquiry/Callback
- Once PayerMax has successfully processed your payment request, you can monitor the payment status through querying the API or callback notifications. Please refer to API Integration - Get Payout Status for integration.
5. Test Go Live
For details regarding the simulation of payout service results and test cases, please refer to Global Payout - Integration and Testing.