API Payout

1. Integration Preparation

• Register developer center account；

• 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;

• Setting up a test environment server IP whitelist；

• Configure and enable the appropriate payment methods；

• View request addresses for different environments；

• Understand the principles of request message signing and verification, for generating a sign signature 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

5.1 Results Simulation

To handle different payment outcomes, the PayerMax Payment API provides a function that simulates different payment statuses based on the transaction amount. The specific rules are as follows:

• Failed: You can set a fixed amount (in local currency): 110 or 11,000;

• Pending: You can set a fixed amount (in local currency): 100 or 10,000;

• Successful: You can set a fixed amount (in local currency): Other amounts.

Special Reminder:

1. If your transaction amount cannot be in your local currency and you still want to simulate a successful or failed transaction, please fill in the remark field: remark=SUCCESS simulates a successful transaction; remark=FAILED simulates a failed transaction; and remark=BOUNCEBACK simulates a bounced transaction.
   If both the remark and the transaction amount meet the simulation conditions, the remark will prevail. For example: remark=SUCCESS, transaction amount=811, the result will be successful.
2. If you are testing a Fawry withdrawal in Egypt and have sent a notifyEmail when placing an order, and would like to receive a withdrawal code via email, please refer to the local currency amount in the payment section above to place an order.

5.2 Test Cases

After completing the product capability access, in order to help merchants verify the Disbursement of collection product functions and understand expected behaviors of each API, PayMax provides developers with complete test cases. You can download on demand according to the real integration:API Single Disbursement Test Cases.