> ## Documentation Index
> Fetch the complete documentation index at: https://safepay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ledger accounts

> Safepay-managed ledger accounts that track balances for Raast aggregators and merchants.

Safepay operates a double-entry ledger for Raast activity. Each aggregator and merchant is mapped to one or more ledger accounts that hold their operational balance, settlement deltas, and fee/tax accruals. These accounts are owned and maintained by Safepay, but you reference them when reading balances or triggering payouts.

Ledger accounts are not bank accounts themselves - they are a real-time representation of what Safepay owes or is owed, backed by settlement runs to your bank account.

<Callout type="info">Raast payments settle in batches every 6 hours. The `running_balance` reflects activity within the current batch and resets to `0` after settlement completes.</Callout>

| Field                    | Description                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `id`                     | Internal numeric identifier for the ledger account.                                                |
| `token`                  | Public, unique ledger account token you reference in APIs.                                         |
| `account_type`           | Type of account (`ACCT_SYSTEM`, `ACCT_MDR_FEE`, `ACCT_MERCHANT`, `ACCT_AGGREGATOR`, tax accounts). |
| `account_name`           | Human-readable label for the account (for example, `Acme Raast settlement`).                       |
| `normal_balance`         | Natural balance side for the account (`SIDE_DEBIT` or `SIDE_CREDIT`), used for applying entries.   |
| `currency`               | ISO 4217 currency code (for example, `PKR`).                                                       |
| `balance`                | Current settled balance in minor units (for example, paisa).                                       |
| `running_balance`        | Balance including pending/soon-to-settle activity, if applicable.                                  |
| `external_partner_id`    | Reference to the upstream partner in Raast Wire.                                                   |
| `external_aggregator_id` | Your aggregator identifier, used to link the account to your integration.                          |
| `external_merchant_id`   | Aggregator merchant identifier when the account is merchant-scoped.                                |
| `vault_token`            | Token referencing the encrypted bank account that receives payouts.                                |
| `bank_acct_id`           | Identifier of the bank account in Raast Wire.                                                      |
| `created_at`             | Timestamp when the ledger account was created.                                                     |
| `updated_at`             | Timestamp of the latest ledger update.                                                             |

### Mapping workflow

<Steps>
  <Step title="List ledger accounts">
    Call `GET /v1/aggregators/{{aggregator_id}}/ledger/accounts` to fetch the aggregator ledger accounts.
  </Step>

  <Step title="Store the ledger token">
    Persist the returned `token`. It is the stable reference used in reconciliation and reporting.
  </Step>

  <Step title="Query merchant ledger accounts">
    Use `GET /v1/aggregators/{{aggregator_id}}/merchants/{{aggregator_merchant_id}}/ledger/accounts` for merchant-level balances.
  </Step>
</Steps>

### Example: list ledger accounts

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/ledger/accounts" \
    --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"
  ```

  ```typescript TypeScript theme={null}
  const baseUrl = '{{base_url}}';
  const aggregatorId = '{{aggregator_id}}';
  const secretKey = '{{secret_key}}';

  const res = await fetch(`${baseUrl}/v1/aggregators/${aggregatorId}/ledger/accounts`, {
    headers: {
      'X-SFPY-AGGREGATOR-SECRET-KEY': secretKey,
    },
  });

  if (!res.ok) {
    throw new Error(`Ledger lookup failed: ${res.status}`);
  }

  const payload = await res.json();
  console.log('Ledger accounts', payload.data);
  ```
</CodeGroup>

## See also

* [Payout lifecycle](/guides/payout-lifecycle)
* [Payouts use case](/use-cases/payouts)
* [Webhooks](/concepts/webhooks)
* [API reference](/api-reference)