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 Status Codes (Returned by Gateway)

These codes are returned in the response_status field and indicate the final status of a transaction; this is for rare cases when the gateway has trouble sending messages to the switch.

Shinkansen Code	Description
`error`	Transfer not processed due to (connection problems, MAC generation or technical issues).

🏦 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.

Shinkansen Code	CCA Code	Description
`approved`	000	Approved transaction
`error_creditor_account_invalid`	041	Invalid destination account
`error_creditor_account_closed`	042	Destination account is closed
`error_creditor_fi_invalid`*	043	Invalid IFR identifier
`error_creditor_rut_invalid`	045	Invalid beneficiary RUT
`error_creditor_rut_account_relation`	046	Invalid RUT and account relationship
`error_transaction_code_invalid`*	047	Incorrect transaction code
`error_transaction_sequence_invalid`*	048	Incorrect transaction sequence
`error_creditor_account_type_disabled`	050	Invalid destination account type
`error_creditor_account_not_found`	051	Destination account not found
`error_amount_field_invalid`	056	Amount field error
`error_debtor_rut_invalid`	057	Invalid origin RUT
`error_duplicate_transaction`	058	Duplicate transaction
`error_required_field_missing`	059	Missing mandatory field
`error_trace_number_invalid`*	060	Invalid trace number
`error_product_account_type_disabled`	061	Product-account type not enabled
`error_amount_exceeds_maximum`	062	Transaction amount exceeds allowed maximum
`error_ifr_service_unavailable`	063	Service unavailable by IFR
`error_creditor_account_over_limits`	064	Destination account restricted for deposits
`error_trace_number_duplicate`*	065	Duplicate trace number, transaction not duplicated

'*' Codes used in the gateway layer

📌 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.

Shinkansen Code	CCA Code	Description
`error_reversal_insufficient_balance`	069	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.

Shinkansen Code	CCA Code	Description
`error_reversal_max_time_conditional`	`009`	Exceeded maximum time to request conditional reversal
`error_reversal_closed_cycle`	`010`	Transaction belongs to a closed settlement cycle
`error_invalid_message`	`011`	Invalid message
`error_reversal_nonexistent_transaction`	`012`	Transaction to reverse not found
`error_reversal_transaction_not_approved`	`013`	Original Transaction not approved and reversal cannot be processed
`error_reversal_duplicated`	`014`	Duplicated reversal already exists
`error_creditor_fi_rejected_by_mac`	`015`	MAC rejected by IFR
`error_switch_rejected_by_mac`	`016`	MAC rejected by Switch
`error_creditor_account_disabled`	`017`	Destination account disabled for TEF
`error_switch_transaction_not_found`	`018`	Queried transaction does not exist
`error_debtor_account_missing`	`020`	Origin account not provided
`error_creditor_account_missing`	`021`	Destination account not provided
`error_creditor_rut_missing`	`025`	Destination RUT not provided
`error_amount_missing`	`028`	Transaction amount not provided
`error_amount_invalid`	`029`	Invalid transaction amount
`error_debtor_fi_missing`	`031`	Origin bank not provided
`error_creditor_fi_missing`	`032`	Destination bank not provided
`error_debtor_fi_invalid`	`033`	Invalid origin bank
`error_creditor_fi_invalid`	`034`	Invalid destination bank
`error_product_codes_missing`	`035`	Product codes not provided (Account types and TEF)
`error_product_codes_invalid`	`036`	Invalid products (Account types and TEF)
`error_creditor_fi_offline`	`037`	Timeout at destination bank or FI offline
`error_creditor_fi_service_unavailable_due_maintenance,`	`038`	Service unavailable due to scheduled maintenance IFR
`error_creditor_fi_offline`	`091`	IFR host unavailable

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 transaction errors (Shinkansen Sandbox)

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

Response Status	Description	CCA	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

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'