How to Build a BaaS Ledger, Part 1: Setting up Your Ledger Architecture
Banking-as-a-service lets fintechs ship banking products without a banking license. What it doesn't give you is a record of who owns what inside your FBO accounts. That record is a ledger, and in this series, we'll build one.
Banking-as-a-Service (BaaS) lets fintechs offer banking products without becoming banks: a sponsor bank holds deposits and moves money, you wrap that relationship in APIs, and fintechs build their products on top. A fintech calls your endpoint, e.g. createTransfer, and real money moves on regulated rails.
By regulation, only banks and licensed institutions can hold customer deposits, so funds must sit at the sponsor bank in FBO (for-benefit-of) accounts: pooled accounts that hold funds on behalf of your fintechs and their customers. Whether it is one pool or several (per fintech), the end user’s money is never in separate accounts per customer.
The bank only ever sees the pool. It can tell you the balance of each FBO account, and nothing more. It doesn't know the fintechs behind the money, and it certainly doesn't know their customers. That breakdown is your commitment, and it runs two levels deep: knowing exactly how much of the money belongs to each fintech, and within each fintech, how much belongs to each of their individual customers.
This is where your ledger comes in. A clear record of every deposit, transfer, and payout, mapped to the right fintech and their customer, periodically reconciled with the bank’s summarized version of the balance. When a fintech asks for their position, the ledger is what answers.
The bank holds the money. The ledger holds the truth about whose money it is. In this series, we’ll build that ledger on Blnk Core, our open-source ledger engine, starting with the ledgers and balances that mirror your FBO structure.
Where Blnk sits in a BaaS stack
Every layer either writes to the ledger or reads from it. The ledger is the source of truth and the authoritative layer for all money movement in your system: if money will move, the ledger should know first.
Whether it is one provider or multiple (deposits sit with the bank, payments through another rail, separate card provider, etc.), the pattern still applies. Everything reports to the ledger first, and that’s how you keep a clear view of everyone’s position regardless of the number of rails behind the scenes.
It's also worth being clear about what Blnk is not:
- Not a payment rail. Blnk records money movement; it doesn't move money. You still need to integrate with your sponsor bank and other providers' APIs.
- Not a KYC verification tool. The identity module stores who your customers are; verification itself happens in your KYC provider.
- Not customer-facing. Never expose Blnk directly to your customers. It sits behind your API service, and exposing it compromises the security of your ledger.
With these boundaries clear, we can start building. Next, we’ll model the ledger itself: how you store and separate balances, and transactions.
Designing your ledger
There are different approaches to designing your ledger. The right ledger design depends on your BaaS: what you offer, how many providers you work with, what you need to report, your future roadmap, etc.
Let’s design for a concrete example. Say your BaaS offers only USD accounts for now. Your fintechs’ customers can deposit and withdraw, and nothing else. The core design question is “How do you cleanly tell the balances apart?” “Which balances belong to which customer / product?”
In most cases, you group by fintech, product, and currency. In Blnk, this “group” is represented with a ledger folder. For example: if Acme Finance signed up to your BaaS program today, their ledger folder name would be AcmeFinance_Accounts_USD.
async function enableAccountService(orgName: string, orgId: string, currency: string) {
return blnk.Ledgers.create({
name: `${orgName}_Accounts_${currency}`,
meta_data: {
org_id: orgId, // the fintech's ID in your system
product: 'Accounts',
currency,
},
});
}
// Onboarding a fintech is one call:
await enableAccountService('AcmeFinance', 'org_3f9a1c', 'USD');
await enableAccountService('OrbitPay', 'org_7b22e0', 'USD');func enableAccountService(orgName, orgID, currency string) (*blnkgo.Ledger, error) {
ledger, _, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
Name: orgName + "_Accounts_" + currency,
MetaData: blnkgo.MetaData{
"org_id": orgID, // the fintech's ID in your system
"product": "Accounts",
"currency": currency,
},
})
return ledger, err
}
// Onboarding a fintech is one call:
enableAccountService("AcmeFinance", "org_3f9a1c", "USD")
enableAccountService("OrbitPay", "org_7b22e0", "USD")def enable_account_service(org_name, org_id, currency):
return blnk.ledgers.create({
"name": f"{org_name}_Accounts_{currency}",
"meta_data": {
"org_id": org_id, # the fintech's ID in your system
"product": "Accounts",
"currency": currency,
},
})
# Onboarding a fintech is one call:
enable_account_service("AcmeFinance", "org_3f9a1c", "USD")
enable_account_service("OrbitPay", "org_7b22e0", "USD")ApiResponse<JsonNode> enableAccountService(String orgName, String orgId, String currency) {
return blnk.ledgers().create(
CreateLedger.create()
.name(orgName + "_Accounts_" + currency)
.metaData(Map.of(
"org_id", orgId, // the fintech's ID in your system
"product", "Accounts",
"currency", currency)));
}
// Onboarding a fintech is one call:
enableAccountService("AcmeFinance", "org_3f9a1c", "USD");
enableAccountService("OrbitPay", "org_7b22e0", "USD");Since we only offer USD accounts, each fintech gets exactly one ledger, and checking a fintech's total position means you only need to look at that one ledger. However, this grouping pattern starts to make more sense when your product starts to grow: a new product or currency can simply be another ledger with a new segment, created the same way, so the work required to add or retire any of them drops to almost nothing.
Say you decide to launch a cards service, and OrbitPay wants in. On Blnk, you don't redesign anything; you run the same pattern with a different product segment:
async function enableCardService(orgName: string, orgId: string, currency: string) {
return blnk.Ledgers.create({
name: `${orgName}_Cards_${currency}`,
meta_data: {
org_id: orgId,
product: 'Cards',
currency,
},
});
}
// Enabling cards for a fintech in your ledger becomes one call:
await enableCardService('OrbitPay', 'org_7b22e0', 'USD');
await enableCardService('AcmeFinance', 'org_3f9a1c', 'EUR');func enableCardService(orgName, orgID, currency string) (*blnkgo.Ledger, error) {
ledger, _, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
Name: orgName + "_Cards_" + currency,
MetaData: blnkgo.MetaData{
"org_id": orgID,
"product": "Cards",
"currency": currency,
},
})
return ledger, err
}
// Enabling cards for a fintech in your ledger becomes one call:
enableCardService("OrbitPay", "org_7b22e0", "USD")
enableCardService("AcmeFinance", "org_3f9a1c", "EUR")def enable_card_service(org_name, org_id, currency):
return blnk.ledgers.create({
"name": f"{org_name}_Cards_{currency}",
"meta_data": {
"org_id": org_id,
"product": "Cards",
"currency": currency,
},
})
# Enabling cards for a fintech in your ledger becomes one call:
enable_card_service("OrbitPay", "org_7b22e0", "USD")
enable_card_service("AcmeFinance", "org_3f9a1c", "EUR")ApiResponse<JsonNode> enableCardService(String orgName, String orgId, String currency) {
return blnk.ledgers().create(
CreateLedger.create()
.name(orgName + "_Cards_" + currency)
.metaData(Map.of(
"org_id", orgId,
"product", "Cards",
"currency", currency)));
}
// Enabling cards for a fintech in your ledger becomes one call:
enableCardService("OrbitPay", "org_7b22e0", "USD");
enableCardService("AcmeFinance", "org_3f9a1c", "EUR");Every card balance belonging to OrbitPay’s customers now sits in OrbitPay_Cards_USD, while AcmeFinance created EUR cards instead grouped in AcmeFinance_Cards_EUR.
To fetch all ledgers belonging to AcmeFinance, you simply filter the ledgers by the meta_data.org_id. If you want to go one step further, you can also add currency and product filters.
// org_id alone returns every AcmeFinance ledger; product and currency narrow it to one.
const acmeLedgers = await blnk.Search.filter(
{
logical_operator: 'and',
filters: [
{field: 'meta_data.org_id', operator: 'eq', value: 'org_3f9a1c'},
{field: 'meta_data.product', operator: 'eq', value: 'Cards'},
{field: 'meta_data.currency', operator: 'eq', value: 'EUR'},
],
include_count: true,
},
'ledgers',
);// org_id alone returns every AcmeFinance ledger; product and currency narrow it to one.
acmeLedgers, resp, err := client.Ledger.Filter(
blnkgo.FilterParams{
Filters: []blnkgo.Filter{
{
Field: "meta_data.org_id",
Operator: blnkgo.OpEqual,
Value: "org_3f9a1c",
},
{
Field: "meta_data.product",
Operator: blnkgo.OpEqual,
Value: "Cards",
},
{
Field: "meta_data.currency",
Operator: blnkgo.OpEqual,
Value: "EUR",
},
},
IncludeCount: true,
},
)# org_id alone returns every AcmeFinance ledger; product and currency narrow it to one.
acme_ledgers = blnk.search.filter(
{
"logical_operator": "and",
"filters": [
{"field": "meta_data.org_id", "operator": "eq", "value": "org_3f9a1c"},
{"field": "meta_data.product", "operator": "eq", "value": "Cards"},
{"field": "meta_data.currency", "operator": "eq", "value": "EUR"},
],
"include_count": True,
},
"ledgers",
)// org_id alone returns every AcmeFinance ledger; product and currency narrow it to one.
ApiResponse<JsonNode> acmeLedgers = blnk.search().filter(
FilterParams.create()
.logicalOperator("and")
.filters(List.of(
FilterCondition.create()
.field("meta_data.org_id")
.operator("eq")
.value("org_3f9a1c"),
FilterCondition.create()
.field("meta_data.product")
.operator("eq")
.value("Cards"),
FilterCondition.create()
.field("meta_data.currency")
.operator("eq")
.value("EUR")))
.includeCount(true),
"ledgers");{
"data": [
{
"ledger_id": "ldg_7f4e2b1a-9c3d-4a5e-b862-1e9d4c7a3f58",
"name": "AcmeFinance_Cards_EUR",
"created_at": "2026-08-27T06:51:03Z",
"meta_data": {
"org_id": "org_3f9a1c",
"product": "Cards",
"currency": "EUR"
}
}
],
"total_count": 1
}Accounts creation and management
Everything that stores value in Blnk is a balance. Cards, wallets, bank accounts, loan accounts: if it holds money, it's a balance. In our example, an OrbitPay customer opening an account means a new balance in OrbitPay_Accounts_USD.
Banks require that every account you issue is tied to a verified identity. So treat identity-first as the fixed order for account opening: create the customer’s identity, then create the balance linked to it.
Create the identity
The identity is the customer as a record in your ledger: who they are, and which fintech they belong to. Extra information goes in
meta_data: the owning org'sorg_id, your internal customer ID, and the KYC status reported by your verification provider.TypeScriptconst identity = await blnk.Identity.create({ identity_type: 'individual', first_name: 'Jordan', last_name: 'Ellis', dob: new Date('1992-03-14'), email_address: '[email protected]', phone_number: '+14155550142', nationality: 'American', category: 'customer', street: '410 Harrison St', city: 'San Francisco', state: 'CA', post_code: '94105', country: 'United States', meta_data: { org_id: 'org_7b22e0', // OrbitPay's ID in your system customer_id: 'cus_8a2f41', kyc_status: 'verified', kyc_provider: 'persona', kyc_verified_at: '2026-08-20T14:32:00Z', risk_tier: 'standard', onboarding_channel: 'orbitpay_ios', }, });Godob, _ := time.Parse(time.RFC3339, "1992-03-14T00:00:00Z") identity, resp, err := client.Identity.Create(blnkgo.Identity{ IdentityType: blnkgo.Individual, FirstName: "Jordan", LastName: "Ellis", DOB: &dob, EmailAddress: "[email protected]", PhoneNumber: "+14155550142", Nationality: "American", Category: "customer", Street: "410 Harrison St", City: "San Francisco", State: "CA", PostCode: "94105", Country: "United States", MetaData: blnkgo.MetaData{ "org_id": "org_7b22e0", // OrbitPay's ID in your system "customer_id": "cus_8a2f41", "kyc_status": "verified", "kyc_provider": "persona", "kyc_verified_at": "2026-08-20T14:32:00Z", "risk_tier": "standard", "onboarding_channel": "orbitpay_ios", }, })Pythonidentity = blnk.identity.create({ "identity_type": "individual", "first_name": "Jordan", "last_name": "Ellis", "dob": "1992-03-14T00:00:00Z", "email_address": "[email protected]", "phone_number": "+14155550142", "nationality": "American", "category": "customer", "street": "410 Harrison St", "city": "San Francisco", "state": "CA", "post_code": "94105", "country": "United States", "meta_data": { "org_id": "org_7b22e0", # OrbitPay's ID in your system "customer_id": "cus_8a2f41", "kyc_status": "verified", "kyc_provider": "persona", "kyc_verified_at": "2026-08-20T14:32:00Z", "risk_tier": "standard", "onboarding_channel": "orbitpay_ios", }, })JavaApiResponse<JsonNode> identity = blnk.identity().create( IdentityData.create() .identityType("individual") .firstName("Jordan") .lastName("Ellis") .dob("1992-03-14T00:00:00Z") .emailAddress("[email protected]") .phoneNumber("+14155550142") .nationality("American") .category("customer") .street("410 Harrison St") .city("San Francisco") .state("CA") .postCode("94105") .country("United States") .metaData(Map.of( "org_id", "org_7b22e0", // OrbitPay's ID in your system "customer_id", "cus_8a2f41", "kyc_status", "verified", "kyc_provider", "persona", "kyc_verified_at", "2026-08-20T14:32:00Z", "risk_tier", "standard", "onboarding_channel", "orbitpay_ios")));Never store sensitive data on the ledger: full card PANs and similar values don't belong in
meta_dataor anywhere else in Blnk. If an identity field needs protection, use PII tokenization: supported fields likefirst_name,email_address, andphone_numbercan be stored as tokens instead of raw values.Return the
identity_idas the ID of the customer. This will be used to create an account for the customer in the next step. Keeping identifiers as close as possible to the ledger means you have less translation code to write/maintain between your backend and the ledger.Create the balance in the right ledger
The balance is the account itself: it lives in the fintech's ledger created when we onboarded them and links back to the identity you just created.
TypeScriptconst balance = await blnk.LedgerBalances.create({ ledger_id: 'ldg_9e2c4a1f-7b3d-4f08-a651-3c8d2e6a9b47', // OrbitPay_Accounts_USD identity_id: identity.identity_id, currency: 'USD', meta_data: { org_id: 'org_7b22e0', // same scoping as the identity customer_id: 'cus_8a2f41', account_number: '0112345678', account_bank: 'Lakeside Bank', account_routing: '110000000', account_type: 'checking', daily_spend_limit: 10000, monthly_withdrawal_limit: 50000, status: 'active', }, });Gobalance, resp, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{ LedgerID: "ldg_9e2c4a1f-7b3d-4f08-a651-3c8d2e6a9b47", // OrbitPay_Accounts_USD IdentityID: identity.IdentityID, Currency: "USD", MetaData: blnkgo.MetaData{ "org_id": "org_7b22e0", // same scoping as the identity "customer_id": "cus_8a2f41", "account_number": "0112345678", "account_bank": "Lakeside Bank", "account_routing": "110000000", "account_type": "checking", "daily_spend_limit": 10000, "monthly_withdrawal_limit": 50000, "status": "active", }, })Pythonbalance = blnk.ledger_balances.create({ "ledger_id": "ldg_9e2c4a1f-7b3d-4f08-a651-3c8d2e6a9b47", # OrbitPay_Accounts_USD "identity_id": identity.data["identity_id"], "currency": "USD", "meta_data": { "org_id": "org_7b22e0", # same scoping as the identity "customer_id": "cus_8a2f41", "account_number": "0112345678", "account_bank": "Lakeside Bank", "account_routing": "110000000", "account_type": "checking", "daily_spend_limit": 10000, "monthly_withdrawal_limit": 50000, "status": "active", }, })JavaApiResponse<JsonNode> balance = blnk.ledgerBalances().create( CreateLedgerBalance.create() .ledgerId("ldg_9e2c4a1f-7b3d-4f08-a651-3c8d2e6a9b47") // OrbitPay_Accounts_USD .identityId(identity.data().get("identity_id").asText()) .currency("USD") .metaData(Map.of( "org_id", "org_7b22e0", // same scoping as the identity "customer_id", "cus_8a2f41", "account_number", "0112345678", "account_bank", "Lakeside Bank", "account_routing", "110000000", "account_type", "checking", "daily_spend_limit", 10000, "monthly_withdrawal_limit", 50000, "status", "active")));200 OK{ "balance": 0, "version": 0, "inflight_balance": 0, "credit_balance": 0, "inflight_credit_balance": 0, "debit_balance": 0, "inflight_debit_balance": 0, "ledger_id": "ldg_9e2c4a1f-7b3d-4f08-a651-3c8d2e6a9b47", "identity_id": "idt_4b8f1c2e-7a3d-4e59-b106-9c2f7a5d8e31", "balance_id": "bln_5d2e8a1c-9f4b-4c37-a820-6e1b3d9f5a72", "indicator": "", "currency": "USD", "created_at": "2026-08-27T07:58:12.442Z", "meta_data": { "org_id": "org_7b22e0", "customer_id": "cus_8a2f41", "account_number": "0112345678", "account_bank": "Lakeside Bank", "account_routing": "110000000", "account_type": "checking", "daily_spend_limit": 10000, "monthly_withdrawal_limit": 50000, "status": "active" } }Scope the balance to its owning org in
meta_data(the sameorg_idyou set on the identity), and use it for account details too: limits, account numbers, and so on. One recommendation: keepmeta_dataflat. Nested objects are harder to filter and query later.
Fetching balances per fintech
Say a fintech calls GET /balances on your API. What you do next depends on how much they want. For every balance they own, resolve the caller's org_id from their API credentials, then simply filter balances by it:
const balances = await blnk.Search.filter(
{
filters: [
{field: 'meta_data.org_id', operator: 'eq', value: 'org_7b22e0'},
],
},
'balances',
);balances, resp, err := client.LedgerBalance.Filter(
blnkgo.FilterParams{
Filters: []blnkgo.Filter{
{
Field: "meta_data.org_id",
Operator: blnkgo.OpEqual,
Value: "org_7b22e0",
},
},
},
)balances = blnk.search.filter(
{
"filters": [
{"field": "meta_data.org_id", "operator": "eq", "value": "org_7b22e0"},
],
},
"balances",
)ApiResponse<JsonNode> balances = blnk.search().filter(
FilterParams.create()
.filters(List.of(
FilterCondition.create()
.field("meta_data.org_id")
.operator("eq")
.value("org_7b22e0"))),
"balances");Every balance we created carries the owning org in its metadata, so this one filter is the whole access boundary. Nothing from another fintech leaks into the response.
If they want something narrower, like all their USD card balances, go through the ledger instead:
Find the org’s USD cards ledger
Filter the ledger list by
org_idfirst:TypeScript// First, find the org's USD cards ledger: const ledgers = await blnk.Search.filter( { filters: [ {field: 'meta_data.org_id', operator: 'eq', value: 'org_7b22e0'}, {field: 'meta_data.product', operator: 'eq', value: 'Cards'}, {field: 'meta_data.currency', operator: 'eq', value: 'USD'}, ], }, 'ledgers', );Go// First, find the org's USD cards ledger: ledgers, resp, err := client.Ledger.Filter( blnkgo.FilterParams{ Filters: []blnkgo.Filter{ { Field: "meta_data.org_id", Operator: blnkgo.OpEqual, Value: "org_7b22e0", }, { Field: "meta_data.product", Operator: blnkgo.OpEqual, Value: "Cards", }, { Field: "meta_data.currency", Operator: blnkgo.OpEqual, Value: "USD", }, }, }, )Python# First, find the org's USD cards ledger: ledgers = blnk.search.filter( { "filters": [ {"field": "meta_data.org_id", "operator": "eq", "value": "org_7b22e0"}, {"field": "meta_data.product", "operator": "eq", "value": "Cards"}, {"field": "meta_data.currency", "operator": "eq", "value": "USD"}, ], }, "ledgers", )Java// First, find the org's USD cards ledger: ApiResponse<JsonNode> ledgers = blnk.search().filter( FilterParams.create() .filters(List.of( FilterCondition.create() .field("meta_data.org_id") .operator("eq") .value("org_7b22e0"), FilterCondition.create() .field("meta_data.product") .operator("eq") .value("Cards"), FilterCondition.create() .field("meta_data.currency") .operator("eq") .value("USD"))), "ledgers");Filter balances by that ledger
Next, fetch balances within that ledger:
TypeScript// Then filter balances by it. The ledger already belongs to // the org, so ledger_id is the only filter you need: const cardBalances = await blnk.Search.filter( { filters: [ {field: 'ledger_id', operator: 'eq', value: ledgers[0].ledger_id}, ], }, 'balances', );Go// Then filter balances by it. The ledger already belongs to // the org, so ledger_id is the only filter you need: firstLedger := ledgers.Data.([]map[string]any)[0] cardBalances, resp, err := client.LedgerBalance.Filter( blnkgo.FilterParams{ Filters: []blnkgo.Filter{ { Field: "ledger_id", Operator: blnkgo.OpEqual, Value: firstLedger["ledger_id"], }, }, }, )Python# Then filter balances by it. The ledger already belongs to # the org, so ledger_id is the only filter you need: card_balances = blnk.search.filter( { "filters": [ {"field": "ledger_id", "operator": "eq", "value": ledgers.data[0]["ledger_id"]}, ], }, "balances", )Java// Then filter balances by it. The ledger already belongs to // the org, so ledger_id is the only filter you need: String ledgerId = ledgers.data().get("data").get(0).get("ledger_id").asText(); ApiResponse<JsonNode> cardBalances = blnk.search().filter( FilterParams.create() .filters(List.of( FilterCondition.create() .field("ledger_id") .operator("eq") .value(ledgerId))), "balances");Any balance inside
OrbitPay_Cards_USDledger belongs to OrbitPay’s Cards based off our design. Filtering again on theorg_iddoesn’t change the result.
What's next
You now have the foundation of a BaaS ledger: ledgers separated by fintech, product, and currency, identities and balances that tie every account to an owner, and a read path that isolates each fintech's data by default.
In the rest of this series, we’ll build on this foundation:
- Transaction workflows: recording deposits, withdrawals, card payments and transfers against these balances.
- Multi-currency & FX: modeling cross-border BaaS products, and tracking your spread and revenue across several fintechs.
- Multi-tenancy: many fintechs on one setup, without them ever seeing each other (hard isolation).
- Sponsor bank reconciliation: ensuring that your ledger and the bank’s version match and catching drifts early when the risk is low.
If you'd like to try this yourself, start with our Sandbox:
