Response Codes & Reversal Codes

Shinkansen classifies and documents all response codes that may be returned during transactions between participants in the low-value payments ecosystem (IFO, IFR, and Switch). These codes help identify the status of a transaction or the reason for a reversal, providing clarity and traceability for integration and error handling.

The response_status values originate from two distinct components of the network: the Switch and the IFR (Receiving Financial Institution).
For this reason, we differentiate between status codes generated and returned by the Switch, and those that are propagated from the IFR when it acts as the final processor of the transaction. Despite their origin, all codes are returned through the same response_status field, providing a unified interface for clients while still allowing clear traceability of where the response was generated within the transaction flow.

These codes are directly related to the following resources:

🏦 Response Transaction Status Codes (Returned by the IFR)

These codes are returned in the response_status field and indicate the final state of a transaction.

Code	Description
`:approved`	Approved transaction
`:error_creditor_account_invalid`	Invalid destination account
`:error_creditor_account_closed`	Destination account is closed
`:error_creditor_account_type_invalid`	Invalid destination account type
`:error_creditor_account_type_disabled`	Destination account type not enabled
`:error_creditor_account_over_limits`	Destination account restricted for deposits
`:error_creditor_account_not_found`	Destination account not found
`:error_creditor_rut_invalid`	Invalid beneficiary RUT
`:error_creditor_rut_account_relation`	Invalid RUT and account relationship
`:error_amount_exceeds_maximum`	Transaction amount exceeds allowed maximum

📌 Note: When Shinkansen Participant is acting as the IFR, it is also required to return the appropriate response_status codes in its response messages. This ensures consistency in error handling across the entire network and allows the originating institution (IFO or Switch) to trace and propagate the correct error back to the user.

↩️ Response Reversal Status Codes (Returned by the IFR)

These codes are returned in the response_status field and indicate the final state of a transaction.

Code	Description
`:error_reversal_insufficient_balance`	Insufficient balance to process reversal

🔀 Response Status Codes (Returned by the Switch)

These codes are returned in the response_status field and indicate the final status of a transaction processed through the Shinkansen Gateway.

Code	Description
`:error_invalid_message`	Invalid message
`:error_switch_transaction_not_found`	Queried transaction does not exist on Switch records
`:error_switch_rejected_by_mac`	MAC rejected by the Switch
`:error_creditor_fi_service_unavailable_due_maintenance`	Service unavailable due to scheduled maintenance
`:error_creditor_fi_offline`	IFR host unavailable
`:error_creditor_fi_timeout`	Timeout at destination bank
`:error_creditor_fi_invalid`	Invalid destination bank
`:error_creditor_fi_rejected_by_mac`	MAC rejected by IFR
`:error_creditor_account_disabled`	Destination account is disabled for TEF
`:error_debtor_fi_invalid`	Invalid debtor fi ID
`:error`	Unspecified error

Reversal Reasons (Returned by Switch or IFO)

These codes are returned in the reversal code field and indicate the reason for the reversal.

Reversal Type	Initiator	Description
`:reversal_switch_timeout`	Switch	Generated when an IFR's "Approved" response arrives after the timeout window has expired.
`:reversal_switch_delivery_failure`	Switch	Generated when an approved response from IFR cannot be delivered to the IFO.
`:reversal_debtor_fi_rejected_by_mac`	Switch	Generated when the IFO rejects an approved response due to a MAC error.
`:reversal_conditional_timeout`	Switch	Generated (optionally) by the Switch when the IFR does not respond to a request in time.
`:reversal_conditional`	IFO	Generated by the IFO when it cannot determine the outcome of a transaction.