Ledgering System

Understand how Rain tracks financial movements using double-entry accounting with balanced ledger entries across accounts and books.

Overview

Rain handles off-chain ledgering using the same fundamental approach banks and accounting systems have used for centuries. Every financial movement creates balanced entries that always sum to zero: what goes out of one account goes into another.

Structure

Rain’s ledger is organized into three layers:

1. Accounts: Each user or company has an account. System accounts also exist for operations like Treasury and Issuing Processor functions.

2. Books: Each account has multiple books that track different types of money movement:

   • Card Pending: Funds on hold from card authorizations that have not yet settled
   • Card Posted: Final, settled transactions (details in the transaction.completed webhook)
   • Fees: Platform fees charged to the customer
   • Due: What the customer owes or is owed

3. Journal Entries: Every transaction creates a journal entry with at least two book entries that balance each other out.

Transaction Flows

Customer deposits funds

When a customer deposits $500:

• Their Due book decreases by $500 (they owe less)
• The Treasury account increases by $500
• Result: Available balance increases by $500

Card authorization

When a customer authorizes a $100 purchase:

• $100 goes into the customer’s Pending book as a hold
• The payment processor’s authorization book records the same $100
• Result: Available balance decreases by $100 immediately, even though the transaction has not settled

Card transaction settles

When the $100 transaction settles:

• The $100 hold is released from the Pending book
• $100 moves to the Posted book (now final)
• The payment processor’s cash book is updated
• Result: Available balance stays the same: funds moved from pending to posted

You will receive a transaction.completed webhook when settlement occurs.

Fees charged

When a $5 fee is charged:

• The customer’s Fees Posted book records $5
• The Treasury receives $5
• Result: Available balance decreases by $5

Key Principles

1. Everything balances: Every debit has an equal credit elsewhere. The system does not allow entries that do not sum to zero.

2. Pending vs. Posted matters: Authorizations immediately reduce available balance (pending), then settle into posted transactions. This prevents overspending.

3. Full audit trail: Every entry records exactly when it happened and why, with snapshots of balances at that moment in time.

4. Atomic transactions: All entries for a single financial event are created together or not at all. There are no partial updates that could leave things unbalanced.

Balance Calculation

A customer’s available balance is essentially:

Total funds deposited minus pending holds minus posted charges minus fees minus amounts owed.

The system adds up all the relevant books to show what’s available to spend at any moment.