Get Payout Status

After successfully creating a payment, merchants can obtain the transaction status through the following two methods:

• Payment Query API: This API is used for active polling and can retrieve sub-statuses other than the final status.
  
• Result Notification Callback: This API is used to asynchronously receive the final transaction status. Once PayerMax receives the final transaction status, it will notify the merchant via a callback.

Scenario	Recommended Method	Description
Write transaction status results to the core system	Notification callback	Push final status, high stability
Real-time feedback on the front-end page	Query interface	Pollable, suitable for user waiting scenarios
Callback not received, exception compensation	Query interface	Scheduled compensation tasks
Daily reconciliation, status archiving	Query interface	Supports batch calls, suitable for clearing and reconciliation scenarios

1. Payment Query API

// Interface Path

POST https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry

Transaction Inquiry API supports synchronous return of transaction status and partial transaction information, facilitating merchant-side process control and display. It is suitable for merchants who need to proactively monitor transaction status, particularly in the following scenarios:

• Front-end users awaiting status confirmation (e.g., receiving a notification indicating the arrival progress after a withdrawal);

• Compensation solutions for failed, delayed, or unconfigured callback notifications;

• In operational scenarios, the business system needs to proactively retrieve the latest transaction status to handle user inquiries.

Note:

After making a request in the format specified in the API documentation, if code = APPLY_SUCCESS and msg = Success. in the query response, it means the request was successful, but does not mean the transaction was successful.

The transaction status needs to be determined based on the status field in the returned data body. The transaction status values ​​include:

status	Meaning	Description
PENDING	Processing	The transaction is still being processed and has not been completed.
SUCCESS	Successful	The payment has been successfully disbursed by the paying bank/wallet.
FAILED	Failed	When a payment request fails, PayerMax will return an error code to help you analyze the cause of the failure. For details, please refer to the Transaction Status/Errorcode below.
BOUNCEBACK	Returned Check	In some countries' financial systems, a successful payment may not be final. This may occur due to the following reasons: - The receiving account is frozen or incorrect - The recipient failed to submit the required documents to the receiving bank, resulting in the receiving bank rejecting the payment - Issues with the bank, clearing network, or other unavailable scenarios In these cases, PayerMax will change the order status from successful to returned check and refund the payment to the merchant's corresponding account.

When status = PENDING is returned, you can use the subStatus field to understand the transaction processing progress. The following are the officially defined sub-statuses:

subStatus	Description	Instructions
PEND_RFI_MATERIAL	Submissions Pending	When this status is reached, merchants must upload supplementary transaction materials according to the instructions in the email or merchant backend to continue processing.
REVIEW	Submissions Under Review	Submissions uploaded, awaiting review results (usually 0-3 business days)
TRANSMIT	Transaction Processing	Transaction processing is proceeding normally, no action required.

Note:

The sub-status is only returned when status = PENDING and is used to help determine the progress of the transaction.
If code = ORDER_NOT_EXIST is returned, it is recommended to wait 5 minutes and retry 2 or more times to confirm the status.

2. Payment Result Callback Notification

// Interface Path

POST https://pay-gate-uat.payermax.com/disbursementResultNotifyUrl

When a transaction enters the final state, the platform pushes status information to the merchant's configured notifyUrl through Disbursement Result Notification API. The notification content structure includes order number, status, transaction amount, currency, time, payee information, deduction, and fee information.

Note:

The code and msg fields in the callback request only represent the request information, not the transaction status. You cannot update the transaction result based on code and message. You must determine the transaction status based on the status field in the returned data body.

The value of status includes:

status	Meaning	Description
SUCCESS	Success	The payment was successfully disbursed by the paying bank/wallet
FAILED	Failed	When a payment request fails, PayerMax will return an error code to help you analyze the cause of the failure. For details, please refer to the Transaction Status/Errorcode below.
BOUNCEBACK	Returned Check	In some countries' financial systems, a successful payment may not be final. This may occur due to the following reasons: - The receiving account is frozen or incorrect - The recipient failed to submit the required documents to the receiving bank, resulting in the receiving bank rejecting the payment - Issues with the bank, clearing network, or other unavailable scenarios In these cases, PayerMax will change the order status from successful to returned check and refund the payment to the merchant's corresponding account.

Merchants must respond correctly after receiving the notification. The format is:

{
  "msg": "Success",
  "code": "SUCCESS"
}

Special Reminder:

• PayerMax may retry notifications due to network anomalies; merchants must properly handle idempotency;
• Merchants must respond correctly upon receiving a PayerMax payment result notification. If they do not respond correctly, PayerMax will deem the notification a failure and resend it until it succeeds. (If a notification fails repeatedly, PayerMax will initiate multiple notifications, with a frequency of 0s/30s/300s/600s/3600s/43200s - a total of 6 times.) However, PayerMax cannot guarantee that these notifications will ultimately succeed;
• If the order status is unclear or if you have not received a PayerMax payment result notification, merchants are advised to proactively call PayerMax's Payment Inquiry API to confirm the order status;
• Upon receiving a payment result notification, merchants must update the transaction result based on the status field in the notification. For failed transactions, the error message in the responseCode and responseMsg fields can be used to prompt the user to make corrections.

3. Transaction Status/Errorcode

When a transaction returns a failed or refunded status, you can use Disbursement Result Notification API and Transaction Inquiry API to obtain the reason for the order failure or refund. Please refer to the following error codes and descriptions:

Category	Subcategory	Errorcode	Error Message	Remark
Order Information Verification	Payment Method Availability Verification	PAYMENT_METHOD_NOT_AVAILABLE	The payment method is not available, plz try other payment methods.	This payment method is not available, please try another payment method or contact PayerMax.
		UNSUPPORTED_ACCOUNT_TYPE	Unsupported account type	The account type is not supported, please modify it and retry.
		UNSUPPORTED_BANK	Bank account invalid or bank not supported	Unsupported bank or the account number is invalid. Please check and retry.
	Invalid Transaction Initiation Amount	AMOUNT_LIMIT_UNMATCHED	The single transfer amount does not meet the limit requirements	The transaction amount does not meet the limit requirement, please modify and retry.
		TRANSACTION_MINIMUM_LIMIT	The transaction amount is below the minimum limit.	The transaction amount is lower than the minimum limit, please modify and retry.
		TRANSACTION_MAXIMUM_LIMIT	The transaction amount exceeds the maximum limit.	The transaction amount exceeds the maximum limit. Please modify and retry.
		AMOUNT_NOT_ENOUGH	Insufficient balance	Insufficient balance, please make sure there is enough balance and retry.
		ZERO_DEDUCTION_AMOUNT	Too small transaction amount, the actual deduction amount is 0.	When the deduction currency is different from the payment currency, please ensure that the estimated deduction amount is greater than 0.
		ZERO_CREDITED_AMOUNT	Too small transaction amount, the actual payment amount is 0 after fees deduction.	Please ensure that the estimated payment amount is greater than the handling fee.
	Payee's Transaction Amount Limit	PAYEE_AMOUNT_EXCEED_LIMIT	Exceed user amount limit	The payee's amount limit has been reached. Please contact the payee for confirmation.
		PAYEE_DAILY_AMOUNT_EXCEED_LIMIT	Exceed payee daily cumulative amount limit.	The daily cumulative limit of the payee has been reached. Please contact the payee for confirmation.
		PAYEE_MONTHLY_AMOUNT_EXCEED_LIMIT	Exceed payee monthly cumulative amount limit.	The monthly cumulative limit of the payee has been reached. Please contact the payee for confirmation.
		PAYEE_CUMULATIVE_AMOUNT_EXCEED_LIMIT	Exceed payee cumulative amount limit.	The cumulative limit of the payee has been reached. Please contact the payee for confirmation.
	Payee's Transaction Limit	TRANSACTION_EXCEED_LIMIT	Transaction exceed limit, please retry later.	The cumulative transaction limit has been reached. Please contact the payee for confirmation.
		EXCEED_DAILY_TIME_LIMIT	The payee account has exceeded the daily transaction times limit	The daily transaction limit has been reached. Please contact the payee for confirmation.
		EXCEED_MONTHLY_TIME_LIMIT	The payee account has exceeded the monthly transaction times limit	The monthly transaction limit has been reached. Please contact the payee for confirmation.
	Payee Account Verification	ACCOUNT_BLOCKED	Account blocked or frozen	The account is closed or frozen, please contact the payee for confirmation.
		INVALID_ACCOUNT	Invalid account or not active	The receiving account is invalid or unavailable, please contact the payee for confirmation.
		INVALID_ACCOUNT_FORMAT	Invalid account format	The account format is incorrect, please modify and retry.
		NONEXISTENT_ACCOUNT	Account does not exist.	The account does not exist, please contact the payee for confirmation.
		ACCOUNT_NOT_ACTIVATED	Account not activated.	The account is not activated, please contact the payee for confirmation.
	Sub Merchant Verification	SUBMERCHANT_NOT_REGISTERED	The subMerchantNo is not registered	Unable to find the sub merchant information, please verify.
		SUBMERCHANT_REGISTRATION_FAILED	The subMerchantNo registration failed	The sub merchant information registration failed, please re-register and try again.
	Other Parameters Verification Of Payee	INVALID_BANK_BRANCH	Invalid bank branch	The bank branch number is invalid, please contact the payee for confirmation.
		INVALID_BANKCODE	Invalid bankCode	The bank code is invalid, please contact the payee for confirmation.
		INVALID_PAYEE_NAME	Invalid payee name	The name format is invalid, please modify and retry.
		INVALID_PHONE_NO	Invalid mobile number	Invalid mobile phone number, please contact the payee for confirmation.
		INVALID_ADDRESS	Invalid Address	Invalid address, please modify and retry.
		INVALID_EMAIL	Email address is incorrect.	Invalid email address, please contact the payee for confirmation.
		INVALID_IDENTIFICATION	Invalid identification	The payee's ID information is incorrect, please modify it and retry.
		INVALID_IFSC_CODE	Invalid IFSC Code	Invalid IFSC Code, please contact the payee for confirmation.
		INVALID_OPERATOR	Invalid operator	The mobile phone number cannot be matched to the operator. Please confirm the mobile phone number is correct and retry.
		PROVIDER_REFUSED_PROCESS	Provider refused to process, please recheck the payee information.	The payee information is incorrect, please modify and retry.
	Payment Expired	REDEEMCODE_EXPIRED	RedeemCode has expired	The payee fails to withdraw funds within the agreed time, please contact the payee and retry.
	Payment Element Matching Verification	MISMATCHED_BANK	Account does not match the bank.	The account number and bank do not match, please contact the payee for confirmation.
		MISMATCHED_IDENTIFICATION	The identification type does not match the document number.	The ID type and ID number do not match, please contact the payee for confirmation.
		MISMATCHED_ACCOUNT	Account type does not match the account number.	The account type and account number do not match, please contact the payee for confirmation.
		MISMATCHED_CURRENCY	The specified currency does not match the payee account.	The payee's account is unable to receive payments in the specified currency.
		MISMATCHED_NAME	Payee name does not match the payee account.	The name and account number do not match, please contact the payee for confirmation.
	Risk Control	RFI_BLACKLIST	Rejected due to failure of beneficiary to submit request information	Failure to submit RFI materials, the transaction is rejected.
		DECLINED_BY_RISK	Beneficiary bank rejected credit for a reason. Eg:Declined by risk	Rejected by risk control.
	Other Exceptions	PAYMENT_FAILED	Payment failed	Transaction failed, please contact PayerMax.
		PROVIDER_FAILED_PROCESS	Provider failed to process, please retry later	Transaction failed, please try again later.