Skip to main content
This guide helps you understand how to apply Formance Ledger patterns to real-world financial operations.
Important DisclaimerThe reference implementations provided in this section are illustrative examples only. Your business model, legal obligations, regulatory requirements, and financial operations may differ significantly from what is described here.These examples are designed to demonstrate the flexibility and power of the Formance Ledger, particularly how Numscript serves as an “intent layer” where business and finance teams can collaborate, define, and agree on financial logic in a clear, executable format.Always consult with your legal, compliance, and accounting teams to ensure your implementation meets your specific requirements and regulatory obligations.

​
Example Implementations

Explore detailed examples of common financial operation patterns:

Omnibus Accounts

Managing pooled funds at financial institutions while tracking individual customer liabilities

Payment Acceptance

Handling card payment authorizations, settlements, refunds, and chargebacks

Financial Hosting & Issuing

Operating an issuing program with authorization holds, presentments, and scheme settlements

Stablecoin Operations

Managing on-ramp and off-ramp flows between fiat and blockchain-based stablecoins

​
Purpose of This Section

These example implementation patterns serve multiple goals:
  1. Demonstrate Real-World Patterns: Show how common financial operations can be modeled using the Formance Ledger
  2. Illustrate Numscript’s Power: Highlight how Numscript acts as a bridge between business intent and technical implementation
  3. Provide Starting Templates: Offer patterns you can adapt to your specific needs
  4. Show Best Practices: Demonstrate proper account structures, metadata usage, and transaction modeling

​
Intent-Based Finance

At the heart of the Formance approach is the concept of Numscript as an intent layer. This means:

​
Separation of Concerns

1

Define Actors and Accounts

Your business and finance teams identify all parties involved in your operations: customers, banks, payment processors, internal accounts, liability accounts, etc.Each actor is represented by accounts in the ledger with clear naming conventions and metadata.
2

Map Events and Bookings

Together, teams enumerate all the financial events that can occur in your business: deposits, withdrawals, authorizations, settlements, refunds, chargebacks, minting, burning, etc.Each event translates to specific accounting movements between accounts.
3

Write Numscripts

Once actors, accounts, and events are defined, Numscripts encode the business logic. These scripts become the single source of truth that both business and technical teams can read and validate.
Numscripts are intentionally readable. Your finance team should be able to review a script and confirm it matches their understanding of the business logic.
4

Execute with Variables

When events occur in your system, you simply “play” the appropriate Numscript with the correct variables. The ledger handles the rest: validating constraints, recording transactions, maintaining balances.

​
Benefits of This Approach

  • Business Clarity: Finance and operations teams can understand and validate the logic without deep technical knowledge.
  • Rapid Iteration: Changes to business logic require updating Numscripts, not redeploying entire systems.
  • Consistency: The same Numscript produces the same results, eliminating implementation drift across services.

​
Leveraging Bi-Temporality

A critical feature of the Formance Ledger is bi-temporality, which means every transaction tracks two timestamps:
  • Request Time: When the transaction was submitted to the ledger (machine clock time)
  • Transaction Time: When the transaction is considered to have occurred (business effective time)

​
Why This Matters for Financial Operations

In real-world financial operations, you frequently encounter timing mismatches:
  • Settlement Delays: Payment authorizations happen in real-time, but bank settlements occur T+1 to T+3 days later. Your ledger should reflect the true effective dates of these movements, not just when you learned about them.
  • Batch Processing: Bank statements arrive the next day. You need to record yesterday’s transactions with their correct effective timestamps.
  • Corrections and Adjustments: When errors are discovered or chargebacks occur, you may need to backdate transactions to reflect when they truly should have occurred.
  • Multi-Timezone Operations: Events happening in different timezones need consistent temporal representation.

​
Implementing Bi-Temporality in Your Numscripts

When executing Numscripts for real-world events, always provide the appropriate transaction timestamp, if reporting for point in time balances of accounts is important:
Request with Transaction Time
{
  "script": {
    "plain": "send [USD/2 100.00] (\n  source = @bank:account\n  destination = @user:123:main\n)",
    "vars": {
      "amount": "100.00",
      "userId": "123"
    }
  },
  "timestamp": "2024-10-20T14:30:00Z"  // Business effective time, not current time
}
If you don’t specify a timestamp, the ledger uses the current machine time.
Backdating ConsiderationsWhen inserting backdated transactions (transaction time in the past), the ledger validates that the entire timeline remains consistent. This means a backdated transaction could be rejected if it would cause account balances to become invalid at any point in the future timeline.Plan your account structures and constraints carefully to accommodate late-arriving information, or consider allowing overdraft.

​
Querying at Points in Time

Bi-temporality enables powerful queries:
Query Balance at Specific Time
# Get account balance as it was on October 20th
fctl ledger accounts get user:123:main --pit 2024-10-20T23:59:59Z

# Get all transactions that occurred on October 20th
fctl ledger transactions list --pit-filter "date=2024-10-20"
This is invaluable for:
  • Reconciliation: Match ledger state to bank statements from specific dates
  • Compliance: Show regulators your exact position at any historical moment
  • Auditing: Investigate what the system knew and when
  • Reporting: Generate month-end reports with exact balance snapshots

​
How to Use These Examples

Each example implementation follows a consistent structure:
  1. Concept Introduction: Explains the financial operation in plain language
  2. Key Concepts & Terminology: Defines important terms and patterns specific to the operation
  3. System Actors: Identifies all parties, their roles, and account types (using interactive tabs)
  4. Account Structure: Shows how to organize accounts in the ledger with clear naming conventions
  5. Balances & Periods: Explains timing considerations and balance tracking
  6. Movements & Bookings: Details each financial event with complete Numscript implementations
  7. Executable Examples: Provides playground-linked examples for each transaction type
  8. Advanced Features: Demonstrates how to leverage bi-temporality, metadata, and other ledger capabilities
  9. Next Steps: Links to related implementations and resources
Some edge cases and special scenarios are covered within each transaction pattern section. The issuing financial host implementation includes additional querying patterns for operational monitoring.

​
Adapting to Your Needs

1

Understand the Pattern

Read through the full example to grasp the core concepts and structure.
2

Map to Your Business

Identify how the pattern differs from your specific use case. What actors are different? What events are unique to you?
3

Modify Account Structure

Adapt the account naming and hierarchy to match your organizational needs and reporting requirements.
4

Customize Numscripts

Adjust the scripts to reflect your business rules, constraints, and metadata requirements.
5

Test Thoroughly

Use the sandbox environment to test your adapted patterns with realistic scenarios, including edge cases and error conditions.
6

Validate with Stakeholders

Review the adapted Numscripts with your finance, compliance, and operations teams to ensure alignment.

​
Key Capabilities Demonstrated

Throughout these example implementations, you’ll see how the Formance Ledger handles:

​
Multi-Asset Operations

Accounts are multi-asset by default. The same account structure and Numscripts work across USD, EUR, GBP, stablecoins, or any other asset you define.
Numscript Multi-Asset Example
send [$ASSET] (
  source = @bank:nostro
  destination = @user:main
)
The $ASSET variable makes the script reusable across all currencies.

​
Rich Metadata

Attach business context to accounts and transactions directly within your Numscripts for powerful querying, reporting, and integration. Use set_tx_meta() to add metadata to transactions and set_account_meta() to update account metadata:
Card Authorization with Metadata
vars {
  account $user
  monetary $amount
  string $auth_id
  string $card_scheme
}

// Move funds to authorization hold
send $amount (
  source = {
    @user:main
    @user:credit_line
  }
  destination = @hold:authorization
)

// Attach rich business context
set_tx_meta("payment_method", "card")
set_tx_meta("card_scheme", $card_scheme)
set_tx_meta("authorization_id", $auth_id)
set_tx_meta("merchant_category", "5812")
set_tx_meta("risk_score", "low")
set_tx_meta("settlement_date", "2024-10-22")

// Update account metadata for tracking
set_account_meta($user, "last_transaction_date", "2024-10-20")
set_account_meta($user, "last_auth_id", $auth_id)
Metadata can be any type: strings, numbers, monetary values, portions, or even account references. See the Numscript metadata reference for complete details.

​
Flexible Querying

Find exactly what you need using filters on metadata, balances, timestamps, and more:
Example Queries
# All high-risk transactions from last week
fctl ledger transactions list --metadata "risk_score=high" --after 2024-10-15

# All accounts with pending settlements
fctl ledger accounts list --metadata "status=pending_settlement"

# Total value in authorization holds
fctl ledger aggregate sum --account "hold:**" --asset "USD/2"

​
Constraint Enforcement

Define business rules that the ledger automatically enforces:
  • Prevent overdrafts on customer accounts
  • Ensure sufficient reserves for liabilities
  • Validate transaction amounts and parties
  • Block transactions that violate business logic
Remember: these are starting points, not finished solutions. Your business is unique, and your ledger implementation should reflect that uniqueness while maintaining the clarity and auditability that Formance enables.