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.