{
  "id": "webhook_123",
  "type": "order_updated",
  "date": "2024-01-15T10:30:00Z",
  "payload": {
    "id": "order_456",
    "status": "failed",
    "statusClassification": {
      "primary": "payment_execution_failed",
      "secondary": "insufficient_funds"
    },
    "referenceId": "your-reference-id",
    "price": {
      "total": 5000,
      "currency": "EUR"
    }
  }
}
When instant bank transfers fail, Ivy provides status classifications in the order_updated webhook event to help you understand the failure in detail. Understanding failure reasons helps you provide better user experience and handle edge cases appropriately.

​
Status Classifications

Ivy uses a two-level classification system to categorize payment failures:
​
statusClassification
object
Contains primary and secondary failure classifications when a payment fails.

​
Primary Classifications

​
Payment Authorization Failed

The payment was rejected during the authorization phase, typically due to user action or bank restrictions. Common scenarios:
  • User rejected or cancelled the payment in their bank app
  • User input the wrong credentials with their bank
  • User’s account has restrictions preventing instant transfers
Handling recommendations:
  • Suggest trying again and checking their log in details carefully
  • Suggest retrying with a different bank
  • Suggest checking their bank account for restrictions

​
Payment Execution Failed

The payment was authorized but failed during execution, usually due to technical or account-related issues. Common scenarios:
  • Insufficient funds in the account
  • Account limits exceeded
  • International transfer was blocked by the bank
  • The payment was rejected by the bank
  • Bank system errors or maintenance
  • Payment not settled within the required timeframe
Handling recommendations:
  • For insufficient funds: Suggest checking account balance and retrying
  • For account restrictions: Recommend contacting the bank
  • For settlement failures: Retry the payment, if the original payment later arrives it will be returned

​
Payment Abandoned

The payment process was started but never completed, often due to user inaction. Common scenarios:
  • User closed the browser/app during payment
  • User did not complete the payment in time and the session timed out
  • The user cancelled the payment with their bank side
Handling recommendations:
  • Provide clear messaging about incomplete payments
  • Inform users of the max time within which payments must be completed
  • Offer to restart the payment process

​
Secondary Classifications

​
Authentication Issues

​
wrong_credentials
string
User entered incorrect bank credentials during authentication.
​
incorrect_2fa_response
string
User provided incorrect two-factor authentication response.
​
pin_blocked
string
User’s PIN is blocked - e.g. due to multiple failed attempts.
​
timeout
string
The payment request timed out due to slow response from bank systems.
​
connection_to_bank_failed
string
The users bank is not responding to the payment request.
​
bank_error
string
The bank’s system returned an error during processing.
​
bank_under_maintenance
string
The user’s bank is currently under maintenance.
​
insufficient_funds
string
The user’s account has insufficient funds for the payment.
​
account_limit_exceeded
string
The payment exceeds the user’s account transfer limits.
​
international_transfer_blocked
string
International transfers are blocked for this account.
​
international_transfer_limit_exceeded
string
The payment exceeds international transfer limits.
​
instant_transfers_not_enabled
string
Instant transfers are not enabled for this account.
​
no_active_tan_methods_available
string
No active TAN (Transaction Authentication Number) methods available.
​
user_blocked
string
The user’s account is blocked or restricted.
​
unsupported_bank_account
string
The bank account type is not supported for the requested transfer.
​
payment_rejected
string
The payment was explicitly rejected by the bank.
​
cancelled
string
The payment was cancelled by the user or bank.
​
payment_not_settled
string
The payment was not settled within the required timeframe.

​
Webhook Integration

The order_updated webhook event includes status classification information when payments fail: 
{
  "id": "webhook_123",
  "type": "order_updated",
  "date": "2024-01-15T10:30:00Z",
  "payload": {
    "id": "order_456",
    "status": "failed",
    "statusClassification": {
      "primary": "payment_execution_failed",
      "secondary": "insufficient_funds"
    },
    "referenceId": "your-reference-id",
    "price": {
      "total": 5000,
      "currency": "EUR"
    }
  }
}
Status classifications are only included in webhook payloads when payments fail or are cancelled. Successful payments will not include this field. For detailed information about webhook setup and handling, see the Webhooks documentation.
To understand the complete payment flow and status transitions, see the Payment Status documentation.