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.
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.
The available_balance
is the sum of all posted inbound entries and pending outbound entries. For credit normal ledger accounts, available_amount = posted_credits - pending_debits
; for debit normal ledger accounts, available_amount = posted_debits - pending_credits
.
{
"id": "376687b1-a45a-44fc-ba87-5f6edfad88f8",
"object": "ledger_account",
"live_mode": true,
"name": "David Acevedo account",
"ledger_id": "3def3cbd-bf0a-4c70-9770-4697cf869411",
"description": null,
"lock_version": 5,
"normal_balance": "credit",
"balances": {
"pending_balance": {
"credits": 25000,
"debits": 10000,
"amount": 15000,
"currency": "USD",
"currency_exponent": 2
},
"posted_balance": {
"credits": 20000,
"debits": 0,
"amount": 20000,
"currency": "USD",
"currency_exponent": 2
},
"available_balance": {
"credits": 20000,
"debits": 10000,
"amount": 10000,
"currency": "USD",
"currency_exponent": 2
}
},
"metadata": {
"msa_id": "97",
"venue_id": "442246"
},
"discarded_at": null,
"created_at": "2022-06-28T22:46:46Z",
"updated_at": "2022-06-28T22:46:46Z"
}
You can write a ledger transaction conditional on the resulting balance of a ledger account. To learn more, see Handling Concurrency.
Updated about 1 year ago