Failure Codes
When a transaction fails, Nium returns the relevant ISO return code to let you know.
The International Organization for Standardization (ISO) standardizes messages sent to clients in the event of transaction failures. This standard ensures consistency across currencies, countries, and payout methods. For return codes, Nium specifically uses ISO 20022.
Standardized return codes simplify your integration by reducing the need to translate multiple financial codes and messages.
ISO 20022, a globally recognized standard, also allows clients to pass return codes to end customers. In turn, clients can configure their integration to return Nium’s descriptions and recommended actions in transaction responses.
Returning Nium's descriptions and recommended actions saves time and improves usability by immediately informing users why a transaction failed and how to fix it.
ISO terms
The following terms commonly appear in ISO definitions and return codes used throughout Nium’s transaction failure messages.
| Term | Description |
|---|---|
| Creditor | The beneficiary of the transaction — the person or entity receiving the funds. |
| Debtor | The remitter or sender — the person or entity sending the funds. |
| Dormant Account | An account that has been inactive for a specific period. |
| Identification Code | A unique number used to identify an account, customer, or institution. |
| End Customer | The beneficiary who ultimately receives the funds. |
| Clearing System | A financial network that processes, reconciles, and settles transactions between financial institutions. |
| Remittance Information | Details about a transaction, such as purpose, amount, and parties involved. |
Return codes
The table below lists common ISO 20022 return codes along with Nium's recommended actions.
For more information on the different ISO 20022 codes, see ISO 2022.
| ISO Code | ISO Definition | Description | Recommended Action |
|---|---|---|---|
| AB05 | TimeoutCreditorAgent | Transaction timed out at the creditor's bank. | Temporary issue - Check your wallet for a refund. If refunded, reinitiate the transaction. |
| AB08 | OfflineCreditorAgent | The creditor's bank is offline. | Temporary issue - Nium couldn’t connect to the beneficiary's bank. Check your wallet for a refund. If refunded, reinitiate the transaction. |
| AC01 | IncorrectAccountNumber | The beneficiary's account number format is invalid. | Confirm the correct beneficiary.accountNumber with the beneficiary. Use Nium Verify to validate account details before adding a beneficiary or creating a payout. |
| AC03 | InvalidCreditorAccountNumber | The beneficiary's account number is invalid or missing. | Confirm the correct beneficiary.accountNumber with the beneficiary.Use Nium Verify to validate account details before adding a beneficiary or creating a payout. |
| AC04 | ClosedAccountNumber | The beneficiary's account is closed. | Ask the beneficiary for updated account details. |
| AC06 | BlockedAccount | The beneficiary's account is blocked, dormant, or inactive. | Request updated account details from the beneficiary. |
| AC08 | InvalidBranchCode | The branch code is invalid or missing. | Confirm the routing code is correct. Use the Search Routing Code request. If valid but unsupported, contact Nium support. |
| AC09 | InvalidAccountCurrency | The account doesn’t support the quoted currency. | Confirm with the beneficiary which currencies the account supports. Use the Nium Playbook or Fetch Supported Corridors request to check:
|
| AC12 | InvalidAccountType | The beneficiary’s account type is invalid. | beneficiary.accountType is not supported for the selected payout method. |
| AC13 | InvalidDebtorAccountType | The sender’s account type is missing or invalid. | The remitter.accountType is not supported for the selected payout method. |
| AG01 | TransactionForbidden | The transaction is prohibited due to regulatory restrictions. | Ask the beneficiary for an alternative bank account or payout method. |
| AG03 | TransactionNotSupported | The transaction type is not supported on the beneficiary's account. | Ask the beneficiary for an alternative bank account or payout method. |
| AM09 | WrongAmount | The received amount differs from the expected amount. | Reinitiate the transaction with the correct amount. |
| AM13 | AmountExceedsClearingSystemLimit | The transaction amount exceeds clearing system limits. | Reinitiate the transaction with a lower amount. |
| AM21 | LimitExceeded | The transaction amount exceeds the allowed limit. | Use the Nium Playbook or Fetch Supported Corridors request to check per-user payout limits. If within limits, ask the beneficiary to check with their bank for any additional restrictions. |
| BE07 | MissingDebtorAddress | The sender’s address is missing or incorrect. | Retry the transaction and include all required address details. Use the Nium Playbook or Fetch Supported Corridors request to confirm what fields are required. |
| BE10 | InvalidDebtorCountry | The sender’s country code is missing or invalid. | Ensure remitter.countryCode or originatingFICountry (for on-behalf payouts) is valid. Retry with correct details. |
| BE11 | InvalidCreditorCountry | The beneficiary’s country code is missing or invalid. | Ensure beneficiary.countryCode is valid.Update the beneficiary details and retry the transaction. |
| BE16 | InvalidDebtorIdentificationCode | The sender’s identification number is missing or invalid. | Retry using the correct remitter.identificationNumber format. |
| BE17 | InvalidCreditorIdentificationCode | The beneficiary’s identification code is missing or invalid. | Ask the beneficiary for a correct beneficiaryIdentificationValue. |
| BE18 | InvalidContactDetails | The beneficiary’s contact details are missing or invalid. | Ensure beneficiaryEmail, beneficiaryContactNumber, or beneficiaryContactName are valid.Update the beneficiary details and retry the transaction. |
| DS04 | OrderRejected | The bank rejected the order. | Ask the beneficiary to contact their bank. If rejected in error, retry the transfer |
| DUPL | DuplicatePayment | Duplicate of a previous payment. | If intentional, retry the transfer. |
| FF06 | InvalidCategoryPurposeCode | The category purpose code is missing or invalid. | purposeCode is unsupported for this payout. Try a different payoutMethod. |
| FF07 | InvalidPurpose | The transaction purpose is missing or invalid. | purposeCode is unsupported for this payout method. Try a different payoutMethod. |
| FF10 | BankSystemProcessingError | Bank system error prevented transaction processing. | Temporary issue – Retry the transfer. Nium automatically retries transactions before returning this error. |
| FOCR | FollowingCancellationRequest | Transaction returned as requested. | You requested the return of this transaction. |
| MD06 | RefundRequestByEndCustomer | The end customer requested a refund. | Contact the beneficiary to confirm the refund reason. |
| MD07 | EndCustomerDeceased | The end customer is deceased. | Return the funds to the original sender. |
| MS03 | NotSpecifiedReasonAgentGenerated | No return reason provided by the bank. | Provided when data protection laws restrict specific return codes. |
| MS18 | MissingRelatedRemittanceInformation | Required transaction details are missing. | Confirm all required fields and retry the transaction. |
| NARR | Narrative | Return reason provided in transaction response. | Check the transaction response for details. |
| NOCM | NotCompliant | The beneficiary's account doesn’t meet regulatory requirements (e.g., FICA). | Return the funds to the original sender |
| RC02 | InvalidBankIdentifier | The routing code is missing or invalid. | Verify the routing code. Use the Search Routing Code request. If valid but unsupported, contact Nium support. |
| RR04 | Regulatory Reason | The transaction failed due to regulatory restrictions. | Return the funds to the original sender |
| RC01 | BankIdentifierIncorrect | The bank identifier code format is invalid. | Verify the routing code. Use the Search Routing Code request. If valid but unsupported, contact Nium support. |