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.
Transfer not processed by Switch

Shinkansen Code	Description
`switch_invalid_mac`	Transfer not processed due to MAC generation or technical issues.
`switch_invalid_message`	Invalid message composition, rejected by Switch
`gateway_hsm_connection_failed`	Gateway could not generate MAC with the HSM
`gateway_connection_failed`	Gateway could not deliver the message to the switch
`gateway_internal_error`	Gateway failed while delivering the message to the switch

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_invalid`	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_timeout`	`037`	Timeout at destination bank
`error_creditor_fi_service_unavailable_due_maintenance`	`038`	Service unavailable due to scheduled maintenance IFR
`error_amount_exceeds_maximum_cpbv`	`080`	Amount exceeds maximum limit by CPBV
`error_creditor_fi_offline`	`091`	IFR host unavailable

Reversal Reasons

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.

Participant Webhooks

Integration Testing