Skip to main content

​
What you’ll build

Build a system where each of your end users has a balance, Account Numbers to receive money, and a movement 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 differ in what Fintoc tracks and whether each user needs Know Your Customer (KYC). Start with the pattern that requires the fewest per-user resources 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 balance.
  • KYC: none per user. Only your root Entity is onboarded.
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.
Use this pattern when you track each user’s wallet balance in your database.

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

  • Structure: many Account objects, all under your Entity. Each Account has its own balance and root Account Number.
  • Per-user balance: Fintoc tracks each user’s balance at the Account level. You can view the balance in the dashboard and statements.
  • KYC: none per user.
Set up:
  1. Create an Account by sending POST /v2/accounts with your Entity’s ID. The new Account includes a root Account Number.
  2. On transfer.inbound.succeeded, use data.account_id to identify the user.
  3. Use data.account_id as the source of funds for withdrawals.
Use this pattern when you want Fintoc to track wallet balances per user. This pattern works in Mexico and Chile.

​
Pattern C: one Account per user under their own Entity

  • Structure: many Entity objects (one per client). Each Entity has one or more Account objects and root Account Numbers.
  • Per-user balance: Fintoc tracks each user’s balance at the Account level.
  • KYC: required per Entity. You run KYC through the API without using the dashboard.
Set up:
  1. Create the client’s Entity and run its KYC review through the API. Follow Onboard an Entity by API to create the Entity, upload company and shareholder documents, and submit the onboarding.
  2. Wait for the entity.onboarding.approved webhook or poll the onboarding status to confirm approval.
  3. Create one or more Account objects under the Entity by sending POST /v2/accounts with the Entity’s entity_id. Each Account has its own balance and root Account Number. A client Entity can hold more than one sub-account, as in Pattern B. Outbound transfers show the client’s legal name on the Comprobante Electrónico de Pago, the Mexican payment receipt.
Use this pattern when receipts must show the client’s legal name. For example, a food delivery platform can pay each restaurant under the restaurant’s Mexican tax ID (RFC). This pattern supports onboarding Mexican Entity objects through the API without dashboard steps. For other countries, create the Entity from the dashboard.

​
Choosing between them

This table compares the three wallet patterns: