Handling payout responses
Whenever you receive a response for the payout API, you should check for the status key.
The status key carries the following standard HTTP codes.
| 200 | OK | You request is successful. You can proceed to transaction_status_id to check the status of your transaction. |
| 422 | Unprocessable Entity | If there is a validation failure in the request |
| 401 | Unauthorized | Your API authorisation failed |
| 403 | Forbidden | No required headers found |
| 502 | Bad Gateway | Bank failed to process your request / timeout. You shouldn't mark this transactions as "Failed" based on this response. In some rare cases, these transactions can become successful. |
| 500 | Internal server error | Something went wrong on our side.You shouldn't mark this transactions as "Failed" based on this response. In some rare cases, these transactions can become successful. |
| 412 | Pre-condition failed | Any internal required data missing or if service provider is down .You shouldn't mark this transactions as "Failed" based on this response. In some rare cases, these transactions can become successful. |
Once a transaction is initiated successfully with 200 OK, you will get a response similar to what shown below. Now you can proceed to handle the transaction_status_id.
{
"data": {
"amount": "10.88",
"open_transaction_ref_id": "opentxn709523",
"transaction_status_id": 15,
"transaction_types_id": 2,
"purpose": "Credit to vendor",
"recepient_name": "Amy",
"email_id": "[email protected]",
"mobile_number": "1111111111",
"merchant_ref_id": "AGSH-7DJF-DM5H-HHJ1",
"debit_account_number": "1234567890",
"bank_error_message": null,
"created_at": "12-08-2019 22:11:14"
},
"status": 200
}
Below are the possible values for transaction_status_id. If payout is from connected account
| transaction_status_id | Transaction Status | Status Description |
|---|---|---|
| 15/103/4 | Success | Transaction is successful |
| 16 | Pending | When transaction is initiated after cut-off timings (NEFT/RTGS). |
| 17 | Failure | Transaction Failed |
| 18 | Suspect | Transaction time-out |
| 19 | Canceled | Checker cancel |
| 20 | Processing | When transaction is initiated after cut-off timings (NEFT/RTGS). |
| 21 | Pending for Processing | When transaction is initiated after cut-off timings (NEFT/RTGS). |
| 37/58/63/37 | The transaction failed because IFSC code is not supported for transactions or Invalid. This means either the beneficiary branch is new or not supported by ICICI for transactions | The transaction failed because IFSC code is not supported for transactions or Invalid. This means either the beneficiary branch is new or not supported by ICICI for transactions |
| 353/343 | Failure. There won't be any debit from the account | UPI failure |
| 350 | Pending | Don't reinitiate the transactions. The transaction will get processed in some time. |
Please find the complete list of Transaction status ids here
Below are the possible values for transaction_status_id. If payout is from open pay virtual account
| transaction_status_id | Transaction Status | Status Description |
|---|---|---|
| 1 | Initiated | Payout Initiated |
| 2 | Request File Generated | Payout request file has generated and send to bank |
| 4 / 15 / 103 | Success | Payout Transaction is success |
| 10 | reversed | Transaction has been reversed |
| 37 | Transaction failed because IFSC code is not supported for transactions. This means either the beneficiary branch is new or not supported transactions. Please contact support for enabling transaction for the IFSC code. | Transaction failed because IFSC code is not supported for transactions. This means either the beneficiary branch is new or not supported transactions. Please contact support for enabling transaction for the IFSC code. |
| 353/343 | Failure. There won't be any debit from the account | UPI failure |
| 350 | Pending | Don't reinitiate the transactions. The transaction will get processed in some time. |
Please find the complete list of Transaction status ids here
Apart from the above responses, there are some bank-specific responses which need to be handled. The transaction responses come as 502 as shown below.
{
"data": {
"bank_response_message": "Transaction failed during processing, due to Beneficiary account is blocked\/frozen. [Sandbox]",
"status": 502
}
}
Do not reinitiate a transaction based on status 502 or error responses
Sometimes, transactions get timed out within the bank's systems. These transactions shouldn't be considered as failed and do not re-attempt transaction as it can result in double credits to the beneficiary. The final status of the transaction will take 72 hours to get updated on GET /payouts/{merchant_ref_id} API.