A complete, production-grade Elixir client for the Mercury Banking API.

Installation

def deps do
  [{:mercury, "~> 0.1"}]
end

Quick start

client = Mercury.Client.new("secret-token:mercury_production_...")

{:ok, %Mercury.Page{items: accounts}} = Mercury.Accounts.list(client)

{:ok, account} = Mercury.Accounts.get(client, "account-id")

# Auto-paginating, lazy stream across every page:
client
|> Mercury.Accounts.stream()
|> Enum.each(&IO.inspect/1)

Every read/write function returns {:ok, result} or {:error, exception}. A !-suffixed variant is also available on every function and raises the exception instead (e.g. Mercury.Accounts.get!/2).

Configuration

Mercury.Client.new/2 accepts:

• :base_url — override the API base URL (useful for sandboxes). Defaults to "https://api.mercury.com/api/v1".
• :timeout — per-request timeout in milliseconds. Defaults to 30_000.
• :retry — a Mercury.Retry struct controlling retry behaviour for transient failures. Defaults to Mercury.Retry.default/0.
• :on_request — a 3-arity function (method, url, request_id -> any) called before each request is sent.
• :on_response — a 5-arity function (method, url, request_id, status, duration_ms -> any) called after each response is received.
• :req_options — a keyword list merged into the underlying Req.new/1 call, for full escape-hatch control (custom Finch pool, plugs for testing, proxies, etc).

Errors

All API errors are raised/returned as one of the exception structs under Mercury.*Error (see Mercury.Error for classification predicates like Mercury.Error.rate_limit_error?/1).

Pagination

Every list endpoint has three matching functions:

• list/2 — fetch a single page as a Mercury.Page struct.
• stream/2 — a lazy Stream of individual items across every page, built with Mercury.Pagination.stream/1. Combine with Enum.take/2, Stream.take_while/2, or Enum.to_list/1 as needed.

Webhooks

Mercury.Webhooks.verify_signature/3 validates the Mercury-Signature header on incoming webhook deliveries using constant-time HMAC comparison.