API ReferenceIntegrationsKnowledge Base

Payout Error Codes

Payout Error Codes are returned when a payout is created, but fails for some reason. These are sent as part of the payout response and webhook payloads.

Handy Tips
The error object in the payouts' API response gives more details about the exact reason for a payout failure and the suggested next steps. You can enable these changes from the RazorpayX Dashboard.
Please share this information with your developers and make sure to check if there is any hard mapping for parameters before making this change. Once enabled, these changes cannot be reverted back.

Watch Out!
The failure_reason field would be deprecated from the API response in a few days after enablement to reduce redundancy.

Sample CodeπŸ”—

Copy{ "error": { "description": "IMPS is not enabled on beneficiary account, Retry with different mode", "source": "beneficiary_bank", "reason": "imps_not_allowed", "code": "NA", "step": "NA", "metadata": {} } }
description
string A description for the error. For example, IMPS is not enabled on beneficiary account, Retry with different mode.
source
string Possible values:
  • gateway: Technical error at Razorpay Partner bank.
  • beneficiary_bank: Technical error at beneficiary bank.
  • business: Merchant action required.
  • internal: Technical error at Razorpay's server.
reason
string The error reason. For example, imps_not_allowed.
code
NA Not applicable for Error Codes, value displayed to maintain consistency of error object.
step
NA Not applicable for API Error Codes, value displayed to maintain consistency of error object.
metadata
Null Value Not applicable for API Error Codes, value displayed to maintain consistency of error object.

Complete Payout Error Response CodeπŸ”—

The complete payout error response code:

Copy{ "id": "pout_00000000000001", "entity": "payout", "fund_account_id": "fa_00000000000001", "amount": 1000000, "currency": "INR", "notes": { "notes_key_1": "Tea, Earl Grey, Hot", "notes_key_2": "Tea, Earl Grey… decaf." }, "fees": 0, "tax": 0, "status": "failed", "utr": null, "mode": "IMPS", "purpose": "refund", "reference_id": "Acme Transaction ID 12345", "narration": "Acme Corp Fund Transfer", "batch_id": null, "failure_reason": "IMPS is not enabled on Beneficiary Account", "created_at": 1545383037, "error": { "description": "IMPS is not enabled on beneficiary account, Retry with different mode", "source": "beneficiary_bank", "reason": "imps_not_allowed", "code": "NA", "step": "NA", "metadata": {} } }

Payout Error SourceπŸ”—

Source

Explanation

gateway

Technical error at Razorpay Partner bank.

beneficiary_bank

Technical error at beneficiary bank.

business

Merchant action required.

internal

Technical error at Razorpay's server.

Payout Error Reason and Next StepsπŸ”—

The table below lists the various payout error reasons, the likely reason for the error, and suggests the possible steps you can take to fix the error.

Reason

Explanation

Next Step

gateway_technical_errorπŸ”—

Technical error at Razorpay partner bank/NPCI/Wallet providers. This usually occurs when there is some server issue at the partner bank end.

Retry after some time or reach out to RazorpayX Support from the Dashboard.

beneficiary_bank_offlineπŸ”—

Technical error at beneficiary bank. This usually occurs when there is some server issue at the beneficiary bank end.

Retry after some time or reach out to RazorpayX Support from the Dashboard.

beneficiary_psp_offlineπŸ”—

Technical error at beneficiary payment service provider. This usually occurs when there is some server issue at beneficiary bank end.

Retry after some time or reach out to RazorpayX Support from the Dashboard.

bank_account_invalidπŸ”—

Incorrect beneficiary bank account number.

Please correct the account number and retry.

bank_account_closedπŸ”—

Payout failed as the beneficiary account is closed.

Please check with your contact or reach out to RazorpayX Support from the Dashboard.

bank_account_dormantπŸ”—

Payout failed as beneficiary account is dormant.

Please contact the beneficiary bank.

transaction_limit_exceededπŸ”—

Payout amount greater than the limit supported by the beneficiary account

Check fund transfer limit for the beneficiary bank and retry.

beneficiary_bank_failureπŸ”—

Technical error at beneficiary bank. This usually occurs when there is some server issue at beneficiary bank end.

Retry after some time or reach out to RazorpayX Support from the Dashboard.

beneficiary_bank_rejectedπŸ”—

Payout rejected by beneficiary bank. Please contact the beneficiary bank.

Please check with beneficiary bank or reach out to RazorpayX Support from the Dashboard.

bank_account_frozenπŸ”—

Payout failed as the beneficiary account is frozen.

Please check with the beneficiary bank.

gateway_pendingπŸ”—

Payout pending at Razorpay partner bank/NPCI/Wallet providers.

Status will be updated after 48 working hours.

gateway_timeoutπŸ”—

Technical error at Razorpay partner bank/NPCI/Wallet providers. This usually occurs when there is some server issue at the partner bank end.

Retry after some time or reach out to RazorpayX Support from the Dashboard.

imps_not_allowedπŸ”—

IMPS is not enabled on beneficiary account.

Retry with different mode for fund transfer.

invalid_ifsc_codeπŸ”—

Payout failed as the IFSC is invalid.

Correct the IFSC and retry.

nre_bank_accountπŸ”—

Payout failed as beneficiary account is an NRE account.

Please contact the beneficiary bank.

beneficiary_vpa_invalidπŸ”—

Payout failed due to invalid beneficiary VPA/UPI ID.

Correct the VPA/UPI ID and retry.

server_errorπŸ”—

Technical error. This usually occurs when there is some issue with the server.

Retry after some time or reach out to RazorpayX Support from the Dashboard.

×