When you’re building a product that moves money, it can be challenging to differentiate between money that’s in flight and settled.
Ledgers lets you track money movement in your application. Ledger transactions have a
status field reflecting whether a transaction is in progress, cancelled, or completed.
Creating a Ledger Transaction
Say a user earns $100 from selling products on your marketplace application. You can use a ledger account to track this user’s wallet balance as they accumulate earnings.
When the user decides to withdraw their $100 balance, your application should record the payout in your ledger so that you know the user’s balance has been zeroed out. To actually move the money, you can use the Payment Orders API to initiate an ACH payment.
When the payment is initiated, you would create a ledger transaction with a
pending. This specifies that funds are in the process of moving out of the user’s application balance. Even though funds haven’t moved yet, recording a pending transaction is good practice. It establishes an audit trail and makes sure funds are not accidentally overdrawn from the user’s account.
Updating a Ledger Transaction Status
While a transaction is
pending, it is mutable, meaning you can modify it with a PATCH request. You can also cancel the transaction by setting its status to
archived. You might do this if a payment fails.
When a payment is settled, you can change the corresponding ledger transaction’s status to
posted. Once a ledger transaction posts it is immutable, meaning its status and entries cannot be modified.
If you’re using a ledger transaction to track a Modern Treasury payment, you can automate this process of updating the transaction status. If you tie the ledger transaction to the Modern Treasury payment object, the ledger transaction status will automatically update in parallel with the status of the payment object. Once a ledger transaction is tied to another object, you can no longer manually update its status. For more on how to link ledger transactions to other Modern Treasury objects, see here.
Ledger Account Balances
Ledger accounts have two balances,
posted_balance is the sum of all posted entries on the ledger account.
pending_balance is the sum of all pending and posted entries on the ledger account.
In the example above, while the user’s payout is in progress their wallet ledger account would have a
posted_balance of $100 (because the payout has not yet posted) and a
pending_balance of $0.
Get in Touch
Read more about Ledgers here. If you’re curious about how Modern Treasury can help your business track and move money, get in touch with us here.
Subscribe to Journal updates
Discover product features and get primers on the payments industry.