Transaction Status and Balances

Overview

Ledger transactions have a status field reflecting whether a transaction is in pending, posted, or archived.

Ledger accounts return several different balances based on the statuses of transactions written to those accounts: pending_balance, posted_balance, and available_balance.

Ledger transaction statuses

While a ledger transaction is pending, it is mutable, meaning you can modify it with a PATCH request.

When a payment is settled, you can change the corresponding ledger transaction’s status to posted. You can also cancel the ledger transaction by setting its status to archived. You might do this if a payment fails.

Once a ledger transaction is posted or archived its status and entries are immutable, meaning they cannot be modified. A ledger transaction's metadata can always be updated.

Account balances

Ledger accounts have three balances, pending_balance, posted_balance, and available_balance. All balances under an account have the same currency, but different ledger accounts (even in the same ledger) may have different currencies.

You can learn more about the different balance types and their structure here.

You can write a ledger transaction conditional on the resulting balance of a ledger account. To learn more, see Handling Concurrency.