Learn here what happens when something goes wrong.

Type of errors

There are two types of errors when making payments with Devengo:

  • errors before the payment has been processed
  • errors occurred during payment processing by the banking network

The first group includes errors generated by Devengo for different reasons, from validation errors to technical problems. In contrast, the second group contains errors returned by the banking system once the payment has been sent for processing. This second group includes bank communication problems, destination account problems, etc.

Errors before the payment has been processed

Most of these errors will be returned immediately in the body of the response when you try to create a payment. You will receive a 4XX response with a detailed explanation of the error in its body. It's important to note that the payment has not been created in this case.

  "error": {
    "message": "Invalid account number",
    "code": "invalid_account_number",
    "type": "invalid_request_error"

There are other potential errors in our validation phase or due to technical problems in our systems. Since it happens in the background, you will receive them as webhook notifications.

Errors during payment processing

As we said before, those payment has been executed, but the money couldn't be credited to the third party. You will have access to the original error code from the banking network. Still, since those codes aren't always as straightforward as they should be and they change from one network to another, we have our own error code that will help you to understand not only what the error means but also if they are definitive, if you can resend the same payment and what to do next.

Error codeError typeRetryableDescription
ERR-0001blocked_account🚫The account is temporarily blocked and cannot accept money. User can contact her local branch to unfreeze the bank account
ERR-0002closed_account🚫The account is closed and cannot accept money. User should provide a new bank account
ERR-0003integration_error🚫This is normally an integration error between banks. It might sound crazy but banking rules are subject to interpretation and this might happen
ERR-0004invalid_bank🚫The bank doesn't exist in this banking network anymore. This can happen with banks after mergers and acquisitions and the user has probably received a new bank account number
ERR-0005recoverableβœ…There is a communication error inside the banking chain. You could resend this transaction after a few minutes although this error could last for a few hours sometimes
ERR-0006suspended_bank🚫Destination bank has been removed from the banking network temporarily. This problem normally appears in the instant payment networks so normally you will redirect this payment as non-instant
ERR-0007wrong_account_number🚫The account number is invalid. User should be contacted for a new bank account
ERR-0008wrong_amount🚫The amount is invalid. You should check and fix the request
ERR-0009wrong_operation_code🚫Duplicated operation. You should check and fix the request
ERR-0010other🚫Other reasons. The exact reason is not specified due to privacy laws, but most of the time should be handled like a blocked_account
ERR-0011processor_failureβœ…The payment could not be processed because of an unknown failure.
ERR-0012transaction_reversed🚫Transaction was processed but reverted by destination bank for any reason. The exact reason is not specified due to privacy laws, but most of the time should be handled like an account_been_closed
ERR-0013payment_denied🚫Payment was denied because it could not pass some validation. Most of the time a payment is denied if the amount limits that have been previously configured are exceeded.

Since our processing of transactions is always in the background, you will receive those errors in the tag error of our webhooks or whenever you ask for the details of a payment that has been rejected o reversed previously.

  "code": "ERR-0001",
  "type": "blocked_account",
  "reason": "AG01"

Detailed errors for each network

If you need fine-grained handling of errors coming from the banking system you might use the original error code generated by your payment. You can find a detailed explanation for them in the following URLs.

Testing your code

You can find in our API documentation a list of IBANs that you can use to force some of these errors in our sandbox.