Guía de implementación

Esta guía describe los servicios y endpoints disponibles para operar el producto de Cuentas Virtuales en Fidi X. Está organizada en cuatro niveles que siguen el ciclo de vida natural del producto — desde la configuración inicial hasta la operación diaria.

Antes de comenzar el setup, el cliente debe tomar una decisión que define la estructura de cuentas que necesitará crear:

Decisión previa: ¿Recaudador o Wallet?

Modelo Recaudador — todos los fondos se concentran en ambos lados del balance. No se mantienen saldos individuales por usuario. Es el modelo adecuado para empresas que recaudan pagos de múltiples clientes y solo necesitan el saldo total consolidado — por ejemplo, empresas de cobranza o utilities.

Modelo Wallet — el activo concentra, pero el pasivo mantiene saldos individuales por usuario. Es el modelo adecuado para productos que necesitan saber cuánto tiene cada cliente — por ejemplo, billeteras digitales o cuentas de prepago.

Esta decisión se comunica al equipo de Fidi X durante el onboarding. A partir de ahí, Fidi X configura las cuentas concentradoras necesarias — el cliente no necesita crearlas. El producto queda listo para operar con el modelo elegido.

Aspecto	Recaudador	Wallet
Concentra activo (débito)	Sí	Sí
Concentra pasivo (crédito)	Sí	No
Saldos individuales por usuario	No	Sí
Caso de uso típico	Cobranza, recaudación	Billeteras digitales

Primer paso — Setup de cuentas

El setup establece la estructura de cuentas sobre la que operará el producto. Debe realizarse una vez por organización, antes de comenzar a recibir transferencias.

Endpoint	Método	Razón
Autenticación	`POST`	Obtener el token de acceso necesario para operar todos los demás endpoints
Crear Persona	`POST`	Opcional — solo si el producto necesita identificar y administrar datos de los titulares de las cuentas
Crear Cuenta	`POST`	Crear las cuentas operativas (clearing) y — en modelo Wallet — las cuentas individuales de clientes
Linkear Cuenta Bancaria	`POST`	Asociar cada cuenta virtual a la cuenta corriente del banco sponsor. Genera el alias que debe compartirse con el originador de las transferencias

Cuentas a crear por el cliente según modelo:

En el modelo Recaudador se requieren:

Una o más cuentas operativas de débito (clearing)

Una o más cuentas operativas de crédito (clearing)

En el modelo Wallet se requieren:

Una o más cuentas operativas de débito (clearing)

Una cuenta individual por cada usuario del producto (cuenta de crédito con owner_id del usuario)

Las cuentas concentradoras son configuradas por el equipo de Fidi X durante el onboarding y no requieren acción por parte del cliente.

Segundo paso — Consultar movimientos y saldos

Una vez que el setup está completo y la cuenta virtual comienza a recibir transferencias, estos endpoints permiten consultar el estado del ledger en cualquier momento.

Endpoint	Método	Razón
Obtener Balance de Cuenta	`GET`	Consultar el saldo actual de una cuenta específica
Listar Operaciones por transacción	`GET`	Consultar todas las operaciones asociadas a una transacción específica usando el filtro `transaction_id`
Listar Operaciones	`GET`	Ver el detalle contable de cada transacción — útil para conciliación y auditoría

Las transferencias bancarias entrantes desde el banco sponsor impactan automáticamente los saldos del ledger — no se requiere ninguna acción por parte del cliente para registrarlas.

Adicionalmente, Fidi X genera un archivo diario en formato JSON con el resumen de todas las transferencias recibidas durante el día. Este archivo incluye las mismas notificaciones enviadas vía webhook, consolidadas en un único entregable para facilitar la conciliación al cierre del día.

El mecanismo de entrega del archivo diario está pendiente de definición. Se actualizará esta documentación cuando esté disponible.

Tercer paso — Modificación y ciclo de vida de cuentas

Estos endpoints permiten gestionar el estado de las cuentas a lo largo de su ciclo de vida operativo.

Endpoint	Método	Razón
Obtener Cuenta por ID	`GET`	Verificar el estado actual de una cuenta y si tiene un linkeo bancario activo
Obtener Cuentas Linkeadas	`GET`	Ver todas las cuentas con linkeo activo en el ledger
Suspender Cuenta	`PATCH`	Inhabilitar temporalmente una cuenta — la cuenta deja de operar hasta que sea reactivada
Activar Cuenta	`PATCH`	Reactivar una cuenta previamente suspendida
Deslinkear Cuenta Bancaria	`DELETE`	Remover el linkeo entre una cuenta virtual y su cuenta corriente bancaria
Eliminar Cuenta	`DELETE`	Dar de baja una cuenta de forma permanente — requiere que el saldo sea cero antes de proceder

Cuarto paso — Notificaciones

Los webhooks permiten que el cliente reciba notificaciones en tiempo real cada vez que una transferencia bancaria entrante impacta una cuenta virtual. Es el mecanismo principal para que el producto del cliente reaccione automáticamente a los ingresos de dinero.

Endpoint	Método	Razón
Crear Suscripción Webhook	`POST`	Registrar el endpoint del cliente donde Fidi X enviará las notificaciones de transferencias entrantes
Obtener Suscripción	`GET`	Verificar el estado y la configuración de una suscripción activa
Actualizar Suscripción	`PUT`	Modificar el endpoint de destino o los eventos suscritos
Eliminar Suscripción	`DELETE`	Dar de baja una suscripción de notificaciones

Cada notificación incluye el identificador de la transferencia bancaria, el monto, la cuenta virtual receptora y el estado de la transacción registrada en el ledger.

Formato de notificación — transferencia entrante

Cuando Fidi X recibe una transferencia bancaria en una cuenta virtual, envía una notificación al endpoint registrado del cliente. El mensaje sigue el formato SNS de AWS y contiene dos bloques de información: ledger_data con el registro contable generado en Fidi X, y bank_data con los datos originales de la transferencia bancaria.

{
  "Type": "Notification",
  "MessageId": "9f677cfb-73b6-5a10-942a-1e8c88323c51",
  "TopicArn": "{{topicARN}}",
  "Message": {
    "id": "8047ac23-6b29-4cc2-8736-24d444a70638",
    "type": "transfer.received",
    "time": "2026-05-08T14:55:00.798737268Z",
    "data": {
      "ledger_data": {
        "id": "93054710-f8a5-4867-b663-1d5186647c7a",
        "reference_id": "70196f79-d5c6-408c-a960-115a97777121",
        "ledger_id": "7b35fa34-bfef-4736-971c-90a2996bc892",
        "asset_id": "00000000-0000-0000-0000-000000000000",
        "type": "cash_in",
        "amount": "15",
        "currency": "CLP",
        "status": "POSTED",
        "metadata": {
          "bank_transfer_id": "70196f79-d5c6-408c-a960-115a97777121",
          "partner_id": "4fd99773-cee1-4d10-92dc-e25b7422906e"
        },
        "created_at": "2026-05-08T14:55:00.599481612Z",
        "updated_at": "2026-05-08T14:55:00.622123812Z",
        "posted_at": "2026-05-08T14:55:00.622123716Z"
      },
      "bank_data": {
        "accounting_date": "2026-02-26",
        "amount": "15.00",
        "bank_transfer_id": "70196f79-d5c6-408c-a960-115a97777121",
        "currency": "CLP",
        "description": "Transferencia Banco Chile",
        "destination": {
          "account_number": "0000000000123456789",
          "customer_identification": "19547456-9"
        },
        "executed_at": "2026-02-26T10:30:00Z",
        "metadata": {
          "id_cca": "000000000001"
        },
        "origin": {
          "account_number": "0000000123456789012",
          "customer_identification": "17547898-9",
          "customer_name": "Juan Gonzalez"
        },
        "status": "A",
        "virtual_account_alias": "8000000000000000001"
      }
    }
  },
  "Timestamp": "2026-05-08T14:55:00.859Z",
  "SignatureVersion": "1",
  "Signature": "{{signature}}",
  "SigningCertURL": "{{SigningCertURL}}",
  "UnsubscribeURL": "{{UnsubscribeURL}}",
  "MessageAttributes": {
    "event_type": {
      "Type": "String",
      "Value": "transfer.received"
    }
  }
}

Descripción de los campos principales:

Campo	Descripción
`type`	Tipo de evento. Para transferencias entrantes siempre es `transfer.received`
`ledger_data.id`	Identificador de la transacción registrada en el ledger de Fidi X
`ledger_data.reference_id`	Referencia que vincula la transacción del ledger con la transferencia bancaria
`ledger_data.asset_id`	Identificador del asset. Será reemplazado por `asset_code` en una próxima versión
`ledger_data.amount`	Monto registrado en el ledger
`ledger_data.status`	Estado de la transacción en el ledger. Una transferencia entrante siempre llega como `POSTED`
`bank_data.bank_transfer_id`	Identificador único de la transferencia bancaria asignado por el banco
`bank_data.origin`	Datos del originador de la transferencia — número de cuenta, RUT y nombre
`bank_data.virtual_account_alias`	Alias de la cuenta virtual receptora
`bank_data.status`	Estado de la transferencia en el banco. `A` indica transferencia aceptada

Nota: El campo ledger_data.asset_id será reemplazado por asset_code en una próxima actualización del payload, para ser consistente con el resto de los contratos de la API.

Decisión previa: ¿Recaudador o Wallet?#

Primer paso — Setup de cuentas#

Segundo paso — Consultar movimientos y saldos#

Tercer paso — Modificación y ciclo de vida de cuentas#