Lithic

Production-grade Elixir client for the Lithic API — card issuing, fintech infrastructure, and embedded finance.

Features

• Complete API coverage — all 150+ endpoints across Cards, Payments, ACH, Tokenization, 3DS, Auth Rules, Events, Credit, Transaction Monitoring, and more
• Cursor-based pagination — Page.stream/1 for lazy enumeration across all list endpoints
• Automatic retries — exponential backoff with jitter on 5xx and network errors
• Idempotency keys — auto-generated on every mutating request
• Webhook verification — HMAC-SHA256 for all webhook types (Events, ASA, Tokenization Decisioning, 3DS Decisioning)
• Telemetry — [:lithic, :request_start/stop/exception] events with duration
• Zero dependencies — only req, jason, and telemetry
• Dialyzer + Credo — full typespec coverage and strict linting

Installation

def deps do
  [
    {:lithic, "~> 1.0"}
  ]
end

Configuration

# config/config.exs
config :lithic,
  api_key: System.get_env("LITHIC_API_KEY"),
  environment: :production   # :production | :sandbox

Or pass a client per-request:

client = Lithic.Client.new(api_key: "my_key", environment: :sandbox)
{:ok, card} = Lithic.Cards.create(%{type: "VIRTUAL"}, client: client)

Quick Start

# Create a virtual card
{:ok, card} = Lithic.Cards.create(%{type: "VIRTUAL"})

# Pause it
{:ok, _} = Lithic.Cards.update(card["token"], %{state: "PAUSED"})

# List cards (paginated)
{:ok, page} = Lithic.Cards.list(page_size: 25, state: "OPEN")
page.data      #=> [%{"token" => ..., "type" => "VIRTUAL", ...}, ...]
page.has_more  #=> true

# Lazily stream all cards
Lithic.Cards.stream()
|> Stream.filter(&(&1["state"] == "OPEN"))
|> Enum.take(100)

# Collect all (use carefully on large datasets)
{:ok, all} = Lithic.Cards.list() |> then(fn {:ok, p} -> Lithic.Page.collect_all(p) end)

Payments (ACH)

# Link an external bank account via micro-deposit
{:ok, eba} = Lithic.ExternalBankAccounts.create(%{
  routing_number: "021000021",
  account_number: "1234567890",
  account_type: "CHECKING",
  owner: "Jane Doe",
  owner_type: "INDIVIDUAL",
  verification_method: "MICRO_DEPOSIT"
})

# After deposits arrive (1-3 business days):
{:ok, _} = Lithic.ExternalBankAccounts.verify(eba["token"], %{micro_deposits: [12, 34]})

# Send a payment
{:ok, payment} = Lithic.Payments.create(%{
  financial_account_token: "fa_token",
  external_bank_account_token: eba["token"],
  amount: 5000,        # $50.00
  direction: "DEBIT",
  method: "ACH_NEXT_DAY",
  method_attributes: %{sec_code: "PPD"},
  type: "PAYMENT"
})

Sandbox Simulation

# Full transaction lifecycle
{:ok, txn} = Lithic.Transactions.simulate_authorization(%{
  card_token: "card_token",
  amount: 1000,
  descriptor: "STARBUCKS",
  mcc: "5812"
})

{:ok, _} = Lithic.Transactions.simulate_clearing(txn["token"])
# or
{:ok, _} = Lithic.Transactions.simulate_void(txn["token"])

Auth Rules (V2)

# Create a velocity limit rule
{:ok, rule} = Lithic.AuthRules.create(%{
  name: "Daily spend limit",
  parameters: %{scope: "CARD", limits: [%{limit: 100_00, period: "DAY"}]}
})

# Draft → backtest → promote
{:ok, _} = Lithic.AuthRules.draft(rule["token"], %{parameters: updated_params})
{:ok, bt} = Lithic.AuthRules.request_backtest(rule["token"], %{
  start: "2024-01-01T00:00:00Z",
  end: "2024-03-01T00:00:00Z"
})
{:ok, _} = Lithic.AuthRules.promote(rule["token"])

Webhook Verification

# In your Phoenix controller:
def handle(conn, _params) do
  raw_body    = conn.assigns.raw_body
  signature   = get_req_header(conn, "webhook-signature") |> List.first()
  timestamp   = get_req_header(conn, "webhook-timestamp") |> List.first()
  {:ok, sub}  = Lithic.Events.get_subscription_secret("sub_token")

  case Lithic.Webhook.verify(raw_body, signature, timestamp, secret: sub["secret"]) do
    {:ok, payload} ->
      handle_event(payload["type"], payload)
      send_resp(conn, 200, "ok")
    {:error, reason} ->
      send_resp(conn, 400, reason)
  end
end

Telemetry

# Attach the default structured logger
Lithic.Telemetry.attach_default_logger(level: :info)

# Or write your own handler
:telemetry.attach(
  "my-handler",
  [:lithic, :request_stop],
  fn _event, %{duration: d}, %{method: m, path: p}, _cfg ->
    ms = System.convert_time_unit(d, :native, :millisecond)
    Logger.info("[lithic] #{m} #{p} #{ms}ms")
  end,
  nil
)

Resource Modules

License

MIT