Test mode (Sandbox)

Test mode te permite construir y validar tu integración sin conectar cuentas bancarias reales. Las keys rail_sk_test_… / rail_pk_test_… operan contra un banco fake que devuelve cuentas y movimientos deterministas, con los mismos shapes, eventos y errores que producción.

El modo se infiere del prefijo de la key — no hay parámetro aparte. Una rail_sk_test_… opera en sandbox; una rail_sk_live_… en producción. Los recursos de un modo nunca se ven desde el otro: un sk_test no puede leer un link live (y viceversa).

1. Obtén tus test keys

En dashboard.rail.cl → Para desarrolladores → API keys, crea una key con Modo: Test. El switch Test/Live de la barra superior cambia toda la vista del dashboard (conexiones, eventos, webhooks) al modo elegido.

# Todos los ejemplos usan tu secret key de test:
export RAIL_SK=rail_sk_test_…

2. Credenciales mágicas

En test mode no puedes conectar cuentas reales. Usa el password mágico rail-sandbox + un RUT mágico que selecciona el escenario:

RUT	Password	Escenario
`11.111.111-1`	`rail-sandbox`	Persona — 1 cuenta vista + 1 tarjeta de crédito, ~50 movimientos
`22.222.222-2`	`rail-sandbox`	Empresa — cuenta corriente CLP + USD (requiere `holder_type: business`)
`33.333.333-3`	`rail-sandbox`	MFA challenge — el sync pide un código (mágico: `123456`)
`44.444.444-4`	`rail-sandbox`	Credenciales inválidas — `rejected_credentials`
`55.555.555-5`	`rail-sandbox`	Sin productos — 0 cuentas (cuenta vacía)

Cualquier otro RUT, o un password distinto de rail-sandbox, devuelve credentials_invalid — nunca se dispara un scraping real. La data es determinista por link: el mismo link devuelve siempre los mismos montos y glosas.

En test mode puedes crear un link directo con POST /v1/links — el bank_id es cosmético (la data es fake igual). El sync arranca en background.

curl https://api.rail.cl/v1/links \
  -X POST \
  -H "Authorization: Bearer $RAIL_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "santander",
    "credentials": { "rut": "11.111.111-1", "password": "rail-sandbox" }
  }'

Response (el link arranca pending y sincroniza en background):

{
  "object": "link",
  "id": "link_8a2f4c6e1b9d5037",
  "mode": "test",
  "institution": { "id": "cl_santander", "country": "cl" },
  "status": "pending"
}

4. Espera el sync y lee la data

El link emite refresh_intent.succeeded al terminar (unos segundos). Puedes consultar el refresh_intent o directamente leer las cuentas:

curl "https://api.rail.cl/v1/accounts?link_id=link_8a2f4c6e1b9d5037" \
  -H "Authorization: Bearer $RAIL_SK"

[
  {
    "object": "account",
    "id": "acc_7d2f3a8c1e9b4502",
    "name": "Cuenta Vista",
    "type": "checking",
    "currency": "CLP",
    "balance": { "available": 842000, "current": 842000 },
    "mode": "test"
  },
  {
    "object": "account",
    "id": "acc_1b9d5037a2f4c6e8",
    "name": "Tarjeta de Crédito Visa",
    "type": "credit_card",
    "currency": "CLP",
    "balance": { "available": 2100000, "limit": 3500000 },
    "mode": "test"
  }
]

Los movimientos salen igual que en producción (montos bigint con signo, glosas chilenas realistas):

curl "https://api.rail.cl/v1/accounts/acc_7d2f3a8c1e9b4502/movements?per_page=5" \
  -H "Authorization: Bearer $RAIL_SK"

5. Prueba el flujo MFA

El RUT 33.333.333-3 fuerza un MFA challenge: el refresh_intent pasa a requires_mfa. Responde con el código mágico 123456 para destrabarlo (cualquier otro código lo rechaza). Es el mismo flujo que un banco real con OTP — ideal para validar tu manejo de MFA async. Ver MFA handling.

6. Prueba tus webhooks

Los webhook endpoints registrados en modo test reciben los eventos de tus links de sandbox (refresh_intent.succeeded, link.credentials_invalid, etc.) — aislados de tus endpoints live. Para validar tu receiver (firma HMAC + retry) sin correr un sync, dispara un evento de prueba a demanda:

curl https://api.rail.cl/v1/sandbox/events/fire \
  -X POST \
  -H "Authorization: Bearer $RAIL_SK" \
  -H "Content-Type: application/json" \
  -d '{ "type": "refresh_intent.succeeded" }'

El evento llega a tus endpoints de modo test con IDs centinela (acc_00000000) — es data de prueba, no consultable. Tipos disparables: refresh_intent.succeeded, refresh_intent.failed, refresh_intent.requires_mfa, link.credentials_invalid, link.expired. Ver Webhooks. El widget de Rail Connect, inicializado con tu rail_pk_test_…, corre en modo sandbox: muestra un indicador “Modo prueba” y precarga las credenciales mágicas en el formulario para que las pruebes sin salir del flujo.

<script src="https://widget.rail.cl/v1/embed.js"></script>
<script>
  Rail.openWidget({
    token: 'wt_…',                 // emitido con tu sk_test o pk_test
    publishableKey: 'rail_pk_test_…',
    onSuccess: (et) => { /* canjéalo en tu backend */ },
  });
</script>

Pasar a producción

Cuando tu integración funcione en test, cambia las keys _test_ por _live_ — no cambia nada más de tu código (las URLs, shapes y flujos son idénticos). El único cambio es que cada sync ahora consulta el banco real.

Autenticación

Los 4 tipos de credenciales y el modelo test/live.

Webhooks

Recibe los eventos de tus links de sandbox.

Empezar

Conceptos

Guías

Test mode (Sandbox)

1. Obtén tus test keys

2. Credenciales mágicas

3. Conecta un banco fake (sin widget)

4. Espera el sync y lee la data

5. Prueba el flujo MFA

6. Prueba tus webhooks

Widget en test mode

Pasar a producción

Autenticación

Webhooks

​1. Obtén tus test keys

​2. Credenciales mágicas

​3. Conecta un banco fake (sin widget)

​4. Espera el sync y lee la data

​5. Prueba el flujo MFA

​6. Prueba tus webhooks

​Widget en test mode

​Pasar a producción

Autenticación

Webhooks

1. Obtén tus test keys

2. Credenciales mágicas

3. Conecta un banco fake (sin widget)

4. Espera el sync y lee la data

5. Prueba el flujo MFA

6. Prueba tus webhooks

Widget en test mode

Pasar a producción