Validator - Estructura y Estados

Cuáles son las posibles respuestas del validador

Validator: Estructura

La estructura de una validación es muy sencilla (y familiar si es que has usado alguna de nuestras otras APIs). Así luce una solicitud de validación:

{
  "id": "3c11df48-dfab-41eb-a3c1-b9f90a0da063",
  "account_details": {
    "name": "Romulo Gallegos",
    "identification": {
      "id_schema": "CLID",
      "id": "11111111-1"
    },
    "financial_institution": {
      "fin_id_schema": "SHINKANSEN",
      "fin_id": "SCOTIABANK_CL"
    },
    "account": "1513523451",
    "account_type": "current_account",
    "currency": "CLP",
    "email": "romulo.gallegos@shinkasen.finance"
  }
}

Los campos pueden variar según el país (por ejemplo, en 🇲🇽 no se suele requerir el financial_institution porque un account_type = "clabe" ya contiene la info de ruteo), pero la idea es muy simple. Una validación tiene un identificador y los detalles de la cuenta a verificar junto a los de su supuesto titular.

• El identificador es asignado por tí, y permite manejar idempotencia: es seguro que reintentes con el mismo id si por algún motivo no sabes si la petición tuvo éxito.
• Los detalles de la cuenta suelen incluir información de identificación, de la institución financiera y de la cuenta (puedes visitar la sección de Códigos y Enumeraciones en la sección izquierda para las distintas formas de identificación de personas, tipos de cuenta o bancos).

Como respuesta a tu petición, obtendrás la misma estructura que enviaste, pero con algunos campos extras de timestamping y status.

{
  ...
  "inserted_at": "2023-06-30T08:50:50Z",
  "status": "pending",
  "updated_at": "2023-06-30T08:50:50Z"
}

Validator: Estados

Cuando se crea una validación nace con status = "pending" y por lo tanto no contiene aún el campo response.

Una vez que la validación se ejecuta, el campo status puede tomar sólo dos valores: "error" si no se pudo ejecutar la validación y "performed" si se pudo ejecutar la validación. En ambos casos aparecerá también el campo response que tiene tres sub-campos: return_code, return_messagey invalid_account_details_reason.

Es el campo return_code (dentro de response) el que indicará si la cuenta existe y pertenece a la persona indicada. Existen 3 posibles valores para return_code:

• ✅ "valid_account_details": La cuenta existe y pertenece a la persona indicada.
• ❌ "invalid_account_details": La cuenta no existe o no pertenece a la persona indicada.
• ❓ "unable_to_validate": No se pudo determinar si la cuenta existe o no.

Cuando status = "error" necesariamente return_code = "unable_to_validate".

En caso de que return_code = "invalid_account_details", el campo invalid_account_details_reason te dará más información sobre por qué no se pudo validar la cuenta. Puede darse el caso que Shinkansen Validator no tenga información suficiente para determinar la razones de la invalidez de la cuenta, en cuyo caso invalid_account_details_reason será unknown.

Una validación con response incluido la puedes obtener cuando invocamos tu webhook o cuando haces GET en la url de una validación y su estado ya no es "pending".

Account Access Check (Verificación de Propiedad)

Además de verificar existencia e identidad, puedes verificar que el usuario tiene control real sobre la cuenta. Al enviar perform_account_access_check: true, Shinkansen transfiere un monto aleatorio (entre $1 y $99 CLP) en vez del $1 fijo.

🔑 Esta funcionalidad requiere tener habilitado el producto validator_variable_amount_cl. Solo disponible para CLP.

Cómo funciona

1. Envías una validación con perform_account_access_check: true
2. Shinkansen transfiere un monto aleatorio a la cuenta
3. Cuando la transferencia se confirma, el campo access_check_amount aparece en la respuesta (webhook o polling)
4. Le preguntas al usuario cuánto recibió y comparas con access_check_amount

Request

{
  "id": "mi-id-unico",
  "perform_account_access_check": true,
  "account_details": {
    "name": "Juan Pérez",
    "identification": { "id_schema": "CLID", "id": "12345678-9" },
    "financial_institution": { "fin_id_schema": "SHINKANSEN", "fin_id": "BANCO_BICE_CL" },
    "account": "123456789",
    "account_type": "current_account",
    "currency": "CLP",
    "email": "juan@ejemplo.cl"
  }
}

Respuesta inmediata (pending)

La respuesta inmediata no incluye access_check_amount — porque la transferencia podría fallar:

{
  "id": "mi-id-unico",
  "perform_account_access_check": true,
  "status": "pending",
  ...
}

Respuesta final (performed)

Cuando la transferencia se confirma, el access_check_amount aparece:

{
  "id": "mi-id-unico",
  "perform_account_access_check": true,
  "access_check_amount": 42.0,
  "status": "performed",
  "response": {
    "return_code": "valid_account_details",
    "return_message": "Shinkansen response: 'ok'"
  },
  ...
}

⚠️ Si status = "error", el campo access_check_amount no se incluye. La validación del monto es responsabilidad del cliente, no de Shinkansen.

Docs detallados de APIs relacionadas