Ledger accounts

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.

Raast payments settle in scheduled batches. The running_balance reflects the unsettled delta since the last settle and resets to 0 when a settlement batch is scheduled.

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

List ledger accounts

Call GET /v1/aggregators/{{aggregator_id}}/ledger/accounts to fetch the aggregator ledger accounts.

Store the ledger token

Persist the returned token. It is the stable reference used in reconciliation and reporting.

Query merchant ledger accounts

Use GET /v1/aggregators/{{aggregator_id}}/merchants/{{aggregator_merchant_id}}/ledger/accounts for merchant-level balances.

Example: list ledger accounts

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/ledger/accounts" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

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);

Getting started

Integration guides

Use Cases

Concepts

Reference

Mapping workflow

Example: list ledger accounts

See also

​Mapping workflow

​Example: list ledger accounts

​See also

Mapping workflow

Example: list ledger accounts

See also