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
2.2 Payment - Order Failed
2.3 Transaction Status Query
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.