Sandbox: Simulated Bank

El 'banco' de Shinkansen para tu proceso de integración

¿Qué es?

SimulatedBank es el "banco" de Shinkansen que puedes usar para integrar nuestros diferentes productos. Los bancos reales no suelen tener un ambiente de pruebas en el cual puedas simular una transacción, por ello hemos creado nuestro banco ficticio, llamado Simulated Bank. Aquí puedes tener una cuenta y enviar payouts, generar notificaciones de payins, probar casos de error, y otras acciones más. El propósito de SimulatedBank es que tengas un acercamiento lo más real posible a un ambiente de producción.

Para poder operar con SimulatedBank:

1. Tu organización se crea automáticamente como parte del proceso de onboarding con Shinkansen. Cuando el equipo de Shinkansen te da de alta, se genera tu organización en SimulatedBank junto con cuentas bancarias pre-configuradas para los países habilitados.

2. Recibirás un email de invitación para acceder a SimulatedBank. Regístrate o inicia sesión en https://simulatedbank.shinkansen.tech usando ese correo y acepta la invitación a tu organización.

3. Una vez dentro de tu organización, encontrarás que ya tienes cuentas bancarias configuradas para los países donde operarás. También puedes crear cuentas adicionales a tu preferencia; verás los diferentes tipos de cuentas y divisas disponibles según el país que selecciones.

4. Ahí te aparecerán los datos que deberás usar en el entorno de prueba en el campo debtor de tus transacciones de payout. Cuando uses esos datos como cuenta de origen y uses el endpoint dev.shinkansen.finance, nuestro switch enviará la solicitud al Simulated Bank. El id de SimulatedBank dentro del esquema Shinkansen es SIMULATED_BANK, esto es lo que deberías poner en el campo financial_institution.fin_id si lo necesitas (recordando que para México es suficiente con la cuenta clabe, y en algunos casos en Perú si usas cuentas cci).

Probar Payouts

Para hacer pruebas primero ingresas a una cuenta y presionas el botón que te permite depositar dinero. Ingresa un monto razonable que te permita hacer algunas pruebas (a menos que quieras partir probando el error de falta de fondos 😉).

Luego tienes los siguientes casos:

• Transferir a un destinatario (creditor) en el banco con id SIMULATED_BANK. En ese caso:
  • Te saldrá error de cuenta inexistente si usas una cuenta que no ha sido creada en el banco simulado o es una cuenta para simular un caso de error
  • Funcionará ok si usas una cuenta correcta (si vas a tu dashboard personal, encontrarás un número de cuenta falso a título personal que puedes usar como cuenta de destino en una prueba exitosa)
• Transferir a un destinatario (creditor) en cualquier otro banco. Acá funcionará todo, excepto cuando el destino (creditor) sea cualquiera de los números de cuenta para simular un caso de error
• Nota que cualquier otro escenario será reportado como exitoso.

Cuentas para simular casos de error

Número de cuenta	Tipo de Cuenta	Error que recibirás
99900	current_account, cash_account, savings_account	error
999000000000000000	clabe	error
99900000000000000000	cci	error
99901	current_account, cash_account, savings_account	error_creditor_account_not_found
999010000000000000	clabe	error_creditor_account_not_found
99901000000000000000	cci	error_creditor_account_not_found
99902	current_account, cash_account, savings_account	error_creditor_account_detail_mismatch
999020000000000000	clabe	error_creditor_account_detail_mismatch
99902000000000000000	cci	error_creditor_account_detail_mismatch
99903	current_account, cash_account, savings_account	error_creditor_account_over_limits
999030000000000000	clabe	error_creditor_account_over_limits
99903000000000000000	cci	error_creditor_account_over_limits
99904	current_account, cash_account, savings_account	error_creditor_fi_offline
999040000000000000	clabe	error_creditor_fi_offline
99904000000000000000	cci	error_creditor_fi_offline
99905	current_account, cash_account, savings_account	error_payment_rail_offline
999050000000000000	clabe	error_payment_rail_offline
99905000000000000000	cci	error_payment_rail_offline
99906	current_account, cash_account, savings_account	error_debtor_account_over_limits
999060000000000000	clabe	error_debtor_account_over_limits
99906000000000000000	cci	error_debtor_account_over_limits
99907	current_account, cash_account, savings_account	error_debtor_insufficient_funds
999070000000000000	clabe	error_debtor_insufficient_funds
99907000000000000000	cci	error_debtor_insufficient_funds
99942	current_account, cash_account, savings_account	No habrá respuesta del banco. Usado por Shinkansen para protocolos de timeout, pero puedes usarlo también en caso que desarrolles alertas después de X tiempo sin tener una respuesta del banco.
999420000000000000	clabe	No habrá respuesta del banco. Usado por Shinkansen para protocolos de timeout, pero puedes usarlo también en caso que desarrolles alertas después de X tiempo sin tener una respuesta del banco.
99942000000000000000	cci	No habrá respuesta del banco. Usado por Shinkansen para protocolos de timeout, pero puedes usarlo también en caso que desarrolles alertas después de X tiempo sin tener una respuesta del banco.

Cuentas que simulan rechazos de nómina de Bci

Estas cuentas reproducen los motivos de rechazo que informa Bci al procesar pagos por nómina. Úsalas como cuenta de destino (creditor), con tipo current_account, cash_account o savings_account, para probar cómo tu integración maneja cada caso. Cuando hay dos cuentas para un mismo motivo, la primera simula una nómina rechazada por completo y la segunda una nómina pagada con rechazos. En ambos casos tu payout termina con el error indicado.

Número de cuenta	Motivo que simula	Error que recibirás
99908	Operación duplicada	error
99909	El monto de la nómina excede el máximo permitido	error_debtor_account_over_limits
99910, 99911	Error en la validación de la cuenta	error
99912, 99913	El pago excede el monto máximo	error_debtor_account_over_limits
99914, 99915	Cuenta de destino incorrecta	error_creditor_account_not_found
99916, 99917	Cuenta de destino cerrada	error_creditor_account_not_found
99918, 99919	Relación inválida entre RUT y cuenta corriente	error_creditor_account_detail_mismatch
99920, 99921	La cuenta del beneficiario no existe	error_creditor_account_not_found
99922, 99923	El monto excede el máximo permitido	error_creditor_account_over_limits
99924, 99925	La cuenta no existe	error_creditor_account_not_found
99926, 99927	Cuenta cerrada	error_creditor_account_not_found
99928, 99929	La cuenta no corresponde al RUT	error_creditor_account_detail_mismatch
99930, 99931	Cuenta inactiva	error_creditor_account_not_found
99932	Nómina eliminada por el cliente	error
99933	Cargo no efectuado	error
99934	Nómina caducada	error

Probar una reversa de payout

Así como puedes revertir un payin, también puedes revertir un payout ya enviado para probar el flujo de devoluciones de punta a punta.

Una vez que envías un payout exitoso, este aparece como un movimiento (débito) en la lista de movimientos de la cuenta de origen. Al lado de ese movimiento aparecerá un botón Reverse payout. Al presionarlo se abre un formulario donde eliges el motivo de la devolución (reversal_reason) y confirmas. SimulatedBank entonces:

• Devuelve los fondos a tu cuenta ficticia (un crédito por el monto del payout revertido), y
• Envía una notificación payout_reversal al webhook notification_payout_reversal_endpoint que hayas configurado en tu dashboard en el modo test.

Para entender qué contiene esa notificación y qué significa cada reversal_reason, revisa Payouts y Devoluciones.

Probar Payins Notifications (Y Reversas)

Para probar notificaciones de payins (abonos a tu cuenta), ingresa a tu organización dentro de SimulatedBank, selecciona una cuenta y presiona el botón Deposit money. El formulario viene prellenado con los datos de tu propia cuenta como ordenante; puedes cambiarlos para simular quién te transfiere (nombre, identificación, cuenta y tipo de cuenta), además del monto y la descripción. Al guardar, el depósito siempre genera dos notificaciones, sin que tengas que marcar ninguna opción:

• Una notificación de payin, que llega al webhook de payins que hayas configurado en tu dashboard en el modo test.
• Una notificación de movimientos (account_report) con el saldo actualizado de la cuenta (ver Probar movimientos y cartolas).

También recibes un payin cuando un payout de prueba tiene como destino una cuenta de tu organización en SimulatedBank.

El caso de las reversas de payins es aún más sencillo. Una vez depositado un monto en tu cuenta ficticia, este se agregará a tu lista de movimientos, y al lado del depósito aparecerá un botón Reverse. Si lo presionas, se descontará el monto revertido de tu cuenta ficticia y se enviarán una notificación de payin_reversal y una nueva notificación de movimientos (account_report) con el saldo actualizado. Si quieres saber más sobre esto de las reversas 🇨🇱 te super recomiendo leer este post de nuestro CEO en el que habla sobre esto mismo 😁.

Probar movimientos y cartolas

En el sandbox, la única forma de recibir notificaciones de movimientos y de cartolas es generarlas desde SimulatedBank. Ingresa a una cuenta de tu organización y usa los botones de la parte superior:

Botón	Notificación que se envía	Qué contiene
Generate account report	account_report	El saldo actual de la cuenta y sus últimos movimientos (hasta 100).
Generate account statement	account_statement	La cartola del día (fecha UTC): saldo inicial, saldo final y los movimientos del día (hasta 100).

Cada notificación se envía al webhook correspondiente que hayas configurado en tu dashboard en el modo test (notification_account_report_endpoint para movimientos y notification_account_statement_endpoint para cartolas). Qué webhooks puedes configurar depende de los productos habilitados para tu organización.

Además del botón, SimulatedBank envía un account_report automáticamente cada vez que depositas, reviertes un payin o reviertes un payout en una cuenta de tu organización.

Probar Validator

El entorno dev de Validator te permite probar los 3 posibles return_code que puede devolver el validador:

Número de cuenta	Tipo de Cuenta	Resultado que recibirás
99900	current_account, cash_account, savings_account	❓ unable_to_validate
999000000000000000	clabe	❓unable_to_validate
99901	current_account, cash_account, savings_account	❌invalid_account_details
999010000000000000	clabe	❌invalid_account_details
Cuenta creada en https://simulatedbank.shinkansen.tech	Tipo de cuenta indicado por SimulatedBank	✅ valid_account_details

Probar Payins (Interactivos)

Para probar payins interactivos, solo debes usar la cuenta creada para tu organización en SimulatedBank para rellenar los datos correspondientes al creditor. Una vez enviada la petición a Shinkansen, recibirás en la respuesta una URL (interactive_payment_url) que te dirigirá a SimulatedBank, donde podrás ver el estado de la transacción. Si todo es correcto, debería mostrarse un ✅ indicando que el abono fue exitoso y verías en la lista de movimientos de tu cuenta el monto correspondiente. Además, recibirás la respuesta con el estado ok de la transacción en el webhook que configuraste en tu dashboard. Si la transacción no es exitosa, la URL mostrará un estado pending permanente y recibirás la respuesta en tu webhook con estado error, indicando el motivo del mismo.