# API Payout ## 1. Integration Preparation + [Register developer center account](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-2-register-as-a-developer)； + [Upload test merchant public key](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-4-1-configure-key-information-for-the-test-environment)，get the platform public key, AppID, test merchant number and other integration information； + [Configure the callback address (WebHook)](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-4-2-configure-the-callback-address-for-the-test-environment), including the payment result callback address, refund result callback address, and so on; + [Setting up a test environment server IP whitelist](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-5-setting-up-a-whitelist-of-server-ips-for-the-test-environment)； + [Configure and enable the appropriate payment methods](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-6-open-integrated-payment-methods)； + [View request addresses for different environments](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_2-environmental-information)； + [Understand the principles of request message signing and verification](https://docs.payermax.com/en/202606-version/developer/config-settings.md), for generating a `sign` signature string for each HTTP request Header. ## 2. Interaction Process ### 2.1 Payment - Order Successfully Placed ```mermaid %%{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 ```mermaid %%{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 ```mermaid %%{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](https://docs.payermax.com/en/202606-version/disbursement/element-verification.md) | 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](https://docs.payermax.com/en/202606-version/disbursement/request/api-request.md) | 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](https://docs.payermax.com/en/202606-version/appendix/disbursement/transaction-status.md#_1-payment-query-api) | Optional | https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry | Query the status of each transaction | | [Payment Result Notification](https://docs.payermax.com/en/202606-version/appendix/disbursement/transaction-status.md#_2-payment-result-callback-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](https://docs.payermax.com/en/202606-version/disbursement/inquiry.md) | 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](https://docs.payermax.com/en/202606-version/disbursement/element-verification.md). ### 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](https://docs.payermax.com/en/202606-version/disbursement/request/api-request.md). For detailed interface parameters, please refer to [Disbursement Request API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-paymentOrderPay/post). ::: warning 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](https://docs.payermax.com/en/202606-version/appendix/disbursement/transaction-status.md) 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](https://docs.payermax.com/en/202606-version/disbursement/test-cases.md).