The Ledger Transaction Status

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 status of 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, pending_balance and posted_balance. The posted_balance is the sum of all posted entries on the ledger account.

The 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.