Railsr.Resources.Ledgers (Railsr v1.0.0)

Railsr Ledger API.

A ledger is an account abstraction. GBP ledgers get a sort code + account number; EUR ledgers get an IBAN; virtual ledgers hold non-real assets (points, rewards, internal accounting).

Ledger Types

`ledger_type`	`asset_type`	Description
`"standard-gbp"`	`"gbp"`	UK current account (FPS + BACS)
`"standard-eur"`	`"eur"`	EUR account (SEPA)
`"standard-usd"`	`"usd"`	USD account (SWIFT)
`"virtual"`	`"<custom>"`	Internal / rewards ledger
`"partner"`	varies	Customer-level (non-enduser) ledger

Summary

Functions

create(params, opts \\ [])

Create a new ledger.

credit_virtual(ledger_id, amount, reason \\ "Credit", opts \\ [])

Credit a virtual ledger (add balance without a real payment).

debit_virtual(ledger_id, amount, reason \\ "Debit", opts \\ [])

Debit a virtual ledger (remove balance without a real payment).

dev_credit(ledger_id, amount, currency \\ "GBP", opts \\ [])

PLAY environment only. Artificially credit a ledger with fake funds for testing — no real money is involved.

find_by_iban(iban, opts \\ [])

Look up a ledger by IBAN.

find_by_uk_account(sort_code, account_number, opts \\ [])

Look up a ledger by UK sort code and account number.

get(ledger_id, opts \\ [])

Retrieve a ledger by its ID.

list(query \\ %{}, opts \\ [])

List ledgers.

list_entries(ledger_id, query \\ %{}, opts \\ [])

Get paginated entry history for a ledger.

update(ledger_id, params, opts \\ [])

Update a ledger (metadata only).

wait_for_active(ledger_id, opts \\ [])

Poll until the ledger reaches "active" status or timeout.

Functions

create(params, opts \\ [])

@spec create(
  map(),
  keyword()
) :: {:ok, Railsr.Types.Ledger.t()} | {:error, Railsr.Error.t()}

Create a new ledger.

Required params

:holder_id — enduser ID (or customer ID for partner ledgers)
:holder_type — "enduser" | "customer"
:ledger_type — see table above
:asset_class — "currency" | "virtual"
:asset_type — e.g. "gbp", "eur", "points"

credit_virtual(ledger_id, amount, reason \\ "Credit", opts \\ [])

@spec credit_virtual(String.t(), integer(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Railsr.Error.t()}

Credit a virtual ledger (add balance without a real payment).

:ledger_id
:amount — integer (minor units)
:reason

debit_virtual(ledger_id, amount, reason \\ "Debit", opts \\ [])

@spec debit_virtual(String.t(), integer(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Railsr.Error.t()}

Debit a virtual ledger (remove balance without a real payment).

dev_credit(ledger_id, amount, currency \\ "GBP", opts \\ [])

@spec dev_credit(String.t(), integer(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Railsr.Error.t()}

PLAY environment only. Artificially credit a ledger with fake funds for testing — no real money is involved.

find_by_iban(iban, opts \\ [])

@spec find_by_iban(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Ledger.t()} | {:error, Railsr.Error.t()}

Look up a ledger by IBAN.

find_by_uk_account(sort_code, account_number, opts \\ [])

@spec find_by_uk_account(String.t(), String.t(), keyword()) ::
  {:ok, Railsr.Types.Ledger.t()} | {:error, Railsr.Error.t()}

Look up a ledger by UK sort code and account number.

get(ledger_id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Ledger.t()} | {:error, Railsr.Error.t()}

Retrieve a ledger by its ID.

list(query \\ %{}, opts \\ [])

@spec list(
  map(),
  keyword()
) :: {:ok, [Railsr.Types.Ledger.t()]} | {:error, Railsr.Error.t()}

List ledgers.

Query params (all optional)

:holder_id — filter by enduser/customer
:asset_type — e.g. "gbp"
:status — e.g. "active"
:limit / :offset — pagination

list_entries(ledger_id, query \\ %{}, opts \\ [])

@spec list_entries(String.t(), map(), keyword()) ::
  {:ok, [Railsr.Types.LedgerEntry.t()]} | {:error, Railsr.Error.t()}

Get paginated entry history for a ledger.

Query params

:from — ISO 8601 start datetime
:to — ISO 8601 end datetime
:limit / :offset

update(ledger_id, params, opts \\ [])

@spec update(String.t(), map(), keyword()) ::
  {:ok, Railsr.Types.Ledger.t()} | {:error, Railsr.Error.t()}

Update a ledger (metadata only).

wait_for_active(ledger_id, opts \\ [])

@spec wait_for_active(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Ledger.t()} | {:error, :timeout | Railsr.Error.t()}

Poll until the ledger reaches "active" status or timeout.