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. 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"
    },
    "posted_balance": {
      "credits": 20000,
      "debits": 0,
      "amount": 20000,
      "currency": "USD"
    },
    "available_balance": {
      "credits": 20000,
      "debits": 10000,
      "amount": 10000,
      "currency": "USD"
    }
  },
  "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.


Did this page help you?