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.

🤖 Simulate error responses

It is possible to simulate response errors coming directly from the switch, in order to verify their proper handling

Reversal Response	Description	CCA Error Code	Trigger
`:error_creditor_account_invalid`	Invalid destination account	041	creditor.account = 987654321
`:error_creditor_account_closed`	Destination account is closed	042	creditor.account = 987654311
`:error_creditor_fi_invalid`	Invalid IFR identifier	043	creditor.financial.institution = 'BANCO_BRASIL_CL'
`:error_creditor_rut_account_relation_invalid`	Invalid RUT and account relationship	046	creditor.account = 987654321 & creditor.identification.id = '35600053-6'
`:error_creditor_account_type_disabled`	Account type not enable	050	creditor.account = 987654321 & creditor.account_type = 'savings_account'
`:error_creditor_account_not_found`	Destination account not found	051	creditor.account = 987654111
`:error_amount_field_invalid`	Amount field error	056	amount = 987654321
`:error_amount_exceeds_maximum`	Transaction amount exceeds maximum limit	062	amount >= 999999999
`:error_ifr_service_unavailable`	Service unavailable by IFR	063	creditor.financial_institution = 'BANCO_PARIS_CL'

Simulated errors from Switch

Reversal Response	Description	CCA Error Code	Trigger
`:error_reversal_max_time_conditional`	Exceeded maximum time to request conditional reversal	009	Reversals sent in less than 60 seconds
`:error_reversal_closed_cycle`	Destination account is closed	010	creditor.account = '123456789'
`:error_reversal_nonexistent_transaction`	Transaction to reverse not found	012	creditor.account = '113456789'
`:error_reversal_transaction_not_approved`	Original Transaction not approved and reversal cannot be processed	013	creditor.account = '111456789'
`:error_reversal_duplicated`	Duplicated reversal already exists	014	Sent transactions with the same original_transaction_id
`:error_creditor_account_disabled`	Destination account disabled for TEF	017	creditor.account = '987611111'
`:error_creditor_fi_service_unavailable_due_maintenance`	Service unavailable due to scheduled maintenance IFR	038	creditor.financial_institution='BANCO_BRASIL_CL' and recipient_account = '987111111'
`:error_creditor_fi_offline`	IFR host unavailable	091	creditor.financial_institution='BANCO_PARIS_CL" and recipient_account = '987111111'

Other errors not simulated

Reversal Response	Description	CCA Error Code
`:error_invalid_message`	Invalid message	011
`:error_creditor_fi_rejected_by_mac`	MAC rejected by IFR	015
`:error_switch_rejected_by_mac`	MAC rejected by Switch	016
`:error_switch_transaction_not_found`	Queried transaction does not exist	018
`:error_debtor_account_missing`	Origin account not provided	020
`:error_creditor_account_missing`	Destination account not provided	021
`:error_creditor_rut_missing`	Destination RUT not provided	025
`:error_amount_missing`	Transaction amount not provided	028
`:error_amount_invalid`	Invalid transaction amount	029
`:error_debtor_fi_missing`	Origin bank not provided	031
`:error_creditor_fi_missing`	Destination bank not provided	032
`:error_debtor_fi_invalid`	Invalid origin bank	033
`:error_creditor_fi_invalid`	Invalid destination bank	034
`:error_product_codes_missing`	Product codes not provided (Account types and TEF)	035
`:error_product_codes_invalid`	Invalid products (Account types and TEF)	036
`:error_creditor_fi_offline`	Timeout at destination bank or FI offline	037
`:error_creditor_rut_invalid`	Invalid beneficiary RUT	045
`:error_transaction_code_invalid`	Incorrect transaction code	047
`:error_transaction_sequence_invalid`	Incorrect transaction sequence	048
`:error_debtor_rut_invalid`	Invalid origin RUT	057
`:error_required_field_missing`	Missing mandatory field	059
`:error_trace_number_invalid`	Invalid trace number	060
`:error_trace_number_duplicate`	Duplicate trace number, transaction not duplicated	065