Response handling

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.

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

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.

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.