Wallet for end users

What you'll build

Build a system where each of your end users has their own balance, Account Numbers to receive money, and a movements history.

When to use it

Reach for this pattern when your product holds a balance per end user:

• Neobanks and fintech apps.
• B2B platforms holding client funds.
• Marketplaces or gig platforms where sellers accumulate earnings before cashing out.

Three patterns: pick one

You can model a user wallet on Fintoc in three ways. The patterns are ordered by how much Fintoc tracks for you and whether each user needs Know Your Customer (KYC). Start with the pattern that needs the least per-user setup and still fits your requirements.

Pattern A: one Account Number per user (virtual Account Numbers)

• Structure: one Fintoc Account (yours) with many Account Numbers, one per user.
• Per-user balance: you track it in your own database. Fintoc holds the aggregate.
• KYC: none per user. Only your root Entity is onboarded.

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

Set up:

1. Use your root Account.
2. Create one Account Number per user with metadata.user_id.
3. On transfer.inbound.succeeded, credit the user's balance in your database.
4. For withdrawals, create an outbound Transfer from your root Account and debit the user's balance in your database.

Good for: wallets where you track each user's balance in your database.

Pattern B: one Account per user under your Entity (sub-accounts)

• Structure: many Account objects, all under your Entity. Each has its own balance and its own root Account Number.
• Per-user balance: Fintoc tracks it at the Account level. Visible in the Dashboard and statements.
• KYC: none per user.

flowchart LR
    S1[Sender for user 1] -->|Incoming transfer| C1[Account Number 1]
    S2[Sender for user 2] -->|Incoming transfer| C2[Account Number 2]
    C1 --> A1[Account: user 1<br/>own balance]
    C2 --> A2[Account: user 2<br/>own balance]
    A1 -.webhook.-> You[(Your backend)]
    A2 -.webhook.-> You

Set up:

1. POST /v2/accounts with your Entity's ID. The Account is created with a root Account Number.
2. On transfer.inbound.succeeded, use data.account_id to identify the user.
3. Withdrawals use that account_id as the source of funds.

Good for: wallets where you want Fintoc to ledger balances per user. Works in Mexico and Chile.

Pattern C: one Account per user under their own Entity

• Structure: many Entity objects (one per client), each with one or more Account objects and root Account Numbers.
• Per-user balance: Fintoc tracks it at the Account level.
• KYC: required per Entity, and you run it by API. No Dashboard step.

flowchart LR
    P[Your platform] -->|Create + onboard by API| E1[Client A Entity]
    P -->|Create + onboard by API| E2[Client B Entity]
    E1 -->|on entity.onboarding.approved| A1[One or more Accounts<br/>under Client A]
    E2 -->|on entity.onboarding.approved| A2[One or more Accounts<br/>under Client B]
    A1 -->|"Mexican payment receipt: Client A name"| O1[Client A bank]
    A2 -->|"Mexican payment receipt: Client B name"| O2[Client B bank]

Set up:

1. Create the client's Entity and run its KYC review by API. The Onboard an Entity by API guide walks the full sequence: create the Entity, upload company and shareholder documents, then submit.
2. Wait for the entity.onboarding.approved webhook, or poll the onboarding, to confirm the Entity is approved.
3. Create one or more Account objects under that Entity with POST /v2/accounts and the Entity's entity_id. Each Account has its own balance and root Account Number. A single client Entity can hold several sub-accounts, as in Pattern B. Outbound transfers from each Account show the client's legal name on the Comprobante Electrónico de Pago, the Mexican payment receipt.

Good for flows where receipts must show the client's legal name, such as a food delivery platform that pays each restaurant under that restaurant's Mexican tax ID (RFC). Use this pattern when you onboard Mexican Entity objects at scale without manual Dashboard steps. For other countries, create the Entity from the Dashboard.

Choosing between them

This table compares the three wallet patterns: