Railsr.Resources.Mandates (Railsr v1.0.0)

Copy Markdown View Source

Railsr Direct Debit Mandate API.

A mandate authorises Railsr to collect money from an enduser's external bank account via BACS Direct Debit and credit it to a Railsr ledger.

Mandate Lifecycle

create → pending → active → (payments) → cancelled | failed

BACS activation takes 3–5 working days after mandate creation. Listen for the mandate-activated webhook before initiating the first payment.

Mandate Statuses

  • "pending" — submitted to BACS, awaiting activation
  • "active" — ready to collect payments
  • "cancelled" — cancelled by enduser or customer
  • "failed" — BACS rejected the mandate

Summary

Functions

cancel(mandate_id, opts \\ [])

Cancel an active mandate.

create(params, opts \\ [])

Create a new Direct Debit mandate.

get(mandate_id, opts \\ [])

Retrieve a mandate by ID.

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

List mandates.

wait_for_active(mandate_id, opts \\ [])

Poll until a mandate reaches active status or timeout.

Functions

cancel(mandate_id, opts \\ [])

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

Cancel an active mandate.

create(params, opts \\ [])

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

Create a new Direct Debit mandate.

Required params

  • :enduser_id
  • :ledger_id — Railsr ledger to credit on collection
  • :account_number — external bank account number
  • :sort_code — external bank sort code
  • :account_holder_name

Optional

  • :reference — shown on the payer's bank statement (max 18 chars)
  • :metadata

get(mandate_id, opts \\ [])

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

Retrieve a mandate by ID.

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

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

List mandates.

Query params

  • :enduser_id
  • :status
  • :limit / :offset

wait_for_active(mandate_id, opts \\ [])

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

Poll until a mandate reaches active status or timeout.

Options

  • :timeout_ms — total wait timeout in ms (default: 600_000)
  • :poll_ms — polling interval in ms (default: 5_000)