Detailed decline reasons reference
This section details the business logic failure codes returned in transaction responses and webhooks when a status is FAILED. These are distinct from HTTP Error Codes (e.g., 401, 500).
A. Payment Decline Reasons
Used for customer payments (POST /payments, GET /transactions/{id}).
| Code | Description | Likely Cause | Recommended Action |
|---|---|---|---|
CURRENCY_NOT_SUPPORTED | Unsupported Currency | The transaction currency is not enabled for this method. | Check supported currencies for the specific APM. |
METHOD_NOT_SUPPORTED | Method Not Supported | The selected payment method is unavailable. | Switch to a different payment method type. |
INVALID_AMOUNT | Invalid Amount | Amount is too low, exceeds limits, or format is wrong. | Verify amount in minor units (no decimals). |
INVALID_ACCOUNT_DETAILS | Invalid Account Data | Incorrect UPI ID, Phone Number, or Bank Account. | Verify customer input and retry with corrected data. |
INVALID_CUSTOMER_DETAILS | Invalid Customer Info | Missing required customer fields (KYC/Email). | Ensure all mandatory customer details are provided. |
LIMIT_EXCEEDED | Transaction Limit Reached | Daily/Monthly limit hit by cardholder/user. | Split transaction or wait for period reset. |
CHANNEL_DOWN | Channel Down | Temporary connectivity issue with the APM provider. | Retry after 1 minute |
CHANNEL_OVERLOADED | Channel overloaded | The channel is overloaded or lacks liquidity | Retry later |
BANK_REJECTED | Bank Rejection | The issuing bank blocked the transaction. | Contact support; user may need to contact their bank. |
KYC_BLOCKED | KYC Verification Failed | User identity verification failed or is pending. | Prompt user to complete KYC in your app. |
TIMEOUT_EXPIRED | Session Timeout | User did not complete action within validity window. | Initiate a new payment request. |
INTERNAL_ERROR | Internal Gateway Error | Unexpected error during processing. | Retry the request; contact support if persistent. |
B. Payout Decline Reasons
Used for merchant withdrawals (POST /payouts, GET /payouts/{id}).
| Code | Description | Likely Cause | Recommended Action |
|---|---|---|---|
CURRENCY_NOT_SUPPORTED | Unsupported Currency | Payout currency does not match wallet currency. | Ensure payout currency matches merchant balance currency. |
METHOD_NOT_SUPPORTED | Method Not Supported | The withdrawal method is unavailable for this region. | Check supported payout methods for your account type. |
INVALID_AMOUNT | Invalid Amount | Amount exceeds minimum/maximum thresholds. | Adjust amount to fall within allowed limits. |
INVALID_ACCOUNT_DETAILS | Invalid Account Data | Recipient bank account or IBAN is incorrect. | Verify recipient details with the beneficiary. |
INSUFFICIENT_BALANCE | Insufficient Balance | Merchant wallet does not have enough funds. | Fund the merchant wallet before requesting payout. |
LIMIT_EXCEEDED | Transaction Limit Reached | Payout limit hit by account restrictions. | Split into multiple transactions or request limit increase. |
CHANNEL_DOWN | Channel Down | Clearing house or bank system is offline. | Retry later (typically T+1). |
CHANNEL_OVERLOADED | Channel overloaded | The channel is overloaded or lacks liquidity | Retry later |
BANK_REJECTED | Bank Rejection | Recipient's bank rejected the incoming transfer. | Verify account number and contact recipient bank. |
FRAUD_SUSPECTED | Fraud Flagged | Transaction triggered security rules. | Contact Tradex World Support for review. |
INTERNAL_ERROR | Internal Gateway Error | Unexpected error during processing. | Retry the request; contact support if persistent. |