> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet para usuarios finales

## Qué vas a construir

Un sistema donde cada uno de tus usuarios finales tiene su propio saldo, sus propios Account Numbers para recibir dinero y un historial de movimientos limpio. El bloque básico para neobancos, marketplaces que mantienen saldos de vendedores, apps para trabajadores gig y cualquier cosa donde "saldo del usuario" sea un concepto de primera clase.

## Cuándo usarlo

* Neobancos y aplicaciones fintech.
* Plataformas B2B que mantienen fondos de clientes.
* Marketplaces o plataformas gig donde los vendedores acumulan ganancias antes de retirarlas.

## Tres patrones — elige uno

Tienes tres formas de modelar el "wallet de usuario" sobre Fintoc, de la más simple a la más rica. Empieza con la más simple que te sirva.

### Patrón A — Un Account Number por usuario (Account Numbers virtuales)

* Estructura: **una** Account de Fintoc (la tuya) con **muchos** Account Numbers, uno por usuario.
* Saldo por usuario: lo llevas en tu propia base de datos. Fintoc mantiene el agregado.
* KYB: ninguno por usuario, solo se onboardea tu Entidad raíz.

```mermaid theme={null}
flowchart LR
    S1[Sender for user 1] -->|SPEI/TEF| C1[Account Number 1]
    S2[Sender for user 2] -->|SPEI/TEF| C2[Account Number 2]
    C1 --> A[Your Account<br/>single total balance]
    C2 --> A
    A -.webhook.-> DB[(Your DB<br/>balance_user1 += amount)]
```

Configuración:

1. Usa tu cuenta raíz.
2. Crea un Account Number por usuario con `metadata.user_id`.
3. En `transfer.inbound.succeeded`, acredita el saldo del usuario en tu base de datos.
4. Para los retiros, crea una Transferencia saliente desde tu cuenta raíz y debita el saldo del usuario en tu base de datos.

Bueno para: wallets ligeras, ganancias, depósito/retiro simples.

### Patrón B — Una Account por usuario bajo tu Entidad (subcuentas)

* Estructura: **muchas** Accounts, todas bajo tu Entidad. Cada una tiene su propio saldo y su propio Account Number raíz.
* Saldo por usuario: Fintoc lo lleva a nivel de Account. Visible en el Dashboard y en los estados de cuenta.
* KYB: ninguno por usuario.

```mermaid theme={null}
flowchart LR
    S1[Sender for user 1] -->|SPEI/TEF| A1[Account: user 1<br/>own Account Number + balance]
    S2[Sender for user 2] -->|SPEI/TEF| A2[Account: user 2<br/>own Account Number + balance]
    A1 -.webhook.-> You[(Your backend)]
    A2 -.webhook.-> You
```

Configuración:

1. `POST /v2/accounts` con el ID de tu Entidad. La Account se crea al instante con un Account Number raíz.
2. En `transfer.inbound.succeeded`, usa `data.account_id` para identificar al usuario.
3. Los retiros usan ese `account_id` como fuente de fondos.

Bueno para: wallets donde quieres que Fintoc lleve los saldos por usuario. Funciona en MX y CL.

### Patrón C — Una Account por usuario bajo su propia Entidad

* Estructura: **muchas** Entidades (una por cliente), cada una con su propia Account y Account Number raíz.
* Saldo por usuario: Fintoc lo lleva a nivel de Account.
* KYB: requerido por Entidad (\~1 día hábil por cliente).

```mermaid theme={null}
flowchart LR
    S1[Customer of A] -->|SPEI/TEF| A1[Account A<br/>Client A Entity]
    S2[Customer of B] -->|SPEI/TEF| A2[Account B<br/>Client B Entity]
    A1 -->|Withdrawal<br/>Receipt (CEP in MX): Client A name| O1[Client A bank]
    A2 -->|Withdrawal<br/>Receipt (CEP in MX): Client B name| O2[Client B bank]
```

Configuración:

1. Crea una Entidad en el Dashboard para el cliente.
2. Fintoc ejecuta el KYB; te notificamos cuando esté aprobado.
3. Una vez aprobada, crea una Account bajo esa Entidad. Las transferencias salientes desde esa Account muestran la razón social del cliente en el CEP.

Bueno para: flujos donde los comprobantes **deben** mostrar el nombre del cliente (por ejemplo, una plataforma de delivery de comida que paga a cada restaurante bajo el RFC/RUT de ese restaurante).

## Cómo elegir entre ellos

|                                                 | Patrón A        | Patrón B | Patrón C |
| ----------------------------------------------- | --------------- | -------- | -------- |
| Saldo por usuario llevado por Fintoc            | ❌ (lo haces tú) | ✅        | ✅        |
| Account Number único por usuario                | ✅               | ✅        | ✅        |
| KYB por usuario                                 | ❌               | ❌        | ✅        |
| Los comprobantes muestran el nombre del usuario | ❌               | ❌        | ✅        |

<br />

<br />