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": "12383287-6"
    },
    "financial_institution": {
      "fin_id_schema": "SHINKANSEN",
      "fin_id": "SCOTIABANK_CL"
    },
    "account": "1513523451",
    "account_type": "current_account",
    "currency": "CLP",
    "email": "[email protected]"
  }
}

Los campos pueden variar según el país (por ejemplo, en 🇲🇽 no se suele requerir el financial_institution porque un account_type = "clave" 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.

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.

❓

Por qué pueden arrojar error las validaciones

Por muchos motivos. Los bancos no siempre tienen 100% de uptime. A veces fallan las redes de interconexión entre ellos. O la información que enviaste en el payload puede estar errada.

Si crees que la información no debiera tener problemas de formato, es buena idea reintentar las validaciones con status = "error". Recuerda realizarla con un nuevo identificador, puesto que el reintento será una nueva validación.

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