Wallet for end users

What it is

Your product needs to hold a separate balance per end user — each with their own CLABE to receive money, the ability to send money out, and a clean movements history. This is the building block behind neobanks, earnings wallets for gig platforms, and marketplaces that hold seller balances.

Fintoc gives you three ways to model this, and the right answer depends on where the per-user balance lives and whose name appears on the receipt.

Best for

Neobanks and fintech apps, B2B platforms that hold client funds, gig / creator platforms with earnings wallets, and any product where "user balance" is a first-class concept.

Three configuration patterns

Pattern	What it looks like	When to use
A. One Account Number per user (virtual CLABEs)	One `Account` (yours). Many `AccountNumbers`, one per user, each with `metadata.user_id`. Balance per user is tracked in your database.	Simple wallets, earnings balances, when the legal holder is you. Fast to set up.
B. One Account per user, under your Entity (sub-accounts)	Many `Accounts`, all under your main `Entity`. Each has its own balance and root CLABE. No additional KYB.	When you want cleaner per-user balances visible directly in Fintoc (Dashboard, statements) without legal segregation. Instant to set up.
C. One Account per user, under their own Entity	Many `Accounts`, each under a separate `Entity` (your client's legal name). Each has its own balance and root CLABE. Requires KYB per Entity.	Products where you manage money on behalf of clients and the receipt (CEP) must show the client's legal name — e.g. food delivery paying out to restaurants.

How the money flows (Pattern A — virtual CLABEs)

flowchart LR
    S1[Sender for user 1] -->|SPEI| C1[CLABE 1]
    S2[Sender for user 2] -->|SPEI| C2[CLABE 2]
    C1 --> A[Your Account<br/>single total balance]
    C2 --> A
    A -.webhook.-> DB[(Your DB<br/>balance_user1 += amount)]

Set it up (Pattern A)

Pick one Account to back the wallet.
For each new user, create an Account Number with metadata.user_id.
On transfer.inbound.succeeded, credit that user's balance in your DB.
For withdrawals, create an outbound transfer (see use case 2) and debit their balance.

How the money flows (Pattern B — sub-accounts under your Entity)

flowchart LR
    S1[Sender for user 1] -->|SPEI| A1[Account: user 1<br/>own CLABE + balance]
    S2[Sender for user 2] -->|SPEI| A2[Account: user 2<br/>own CLABE + balance]
    A1 -.webhook.-> You[(Your backend)]
    A2 -.webhook.-> You

Set it up (Pattern B — sub-accounts under your Entity)

For each new user, create an Account under your existing Entity via POST /v2/accounts.
The Account is created instantly with its own root CLABE and its own balance (visible in Fintoc).
On transfer.inbound.succeeded, use data.account_id to know which user received the money.
Withdrawals use that Account's account_id as the debit source.

How the money flows (Pattern C — one Entity per client)

flowchart LR
    S1[Customer of A] -->|SPEI| A1[Account A<br/>Client A Entity]
    S2[Customer of B] -->|SPEI| A2[Account B<br/>Client B Entity]
    A1 -->|Withdrawal<br/>CEP: Client A name| O1[Client A bank]
    A2 -->|Withdrawal<br/>CEP: Client B name| O2[Client B bank]

Set it up (Pattern C — one Entity per client)

Create a new Entity per client from the Dashboard. KYB typically completes in ~2 days.
Once approved, create an Account under that Entity — it starts with a root CLABE.
Outbound transfers from that Account will show the Entity's legal name on the CEP.