LatticeStripe

Current release:1.7.x on Hex — see CHANGELOG for what shipped since 1.1.0. Evaluating fit? Start with User Flows & JTBD.

A production-grade, idiomatic Elixir SDK for the Stripe API.

Full documentation available on HexDocs.

If you are evaluating how this fits into a real SaaS billing architecture, start with Guide: User Flows & JTBD.

v1.x scope

As of 1.7.0, LatticeStripe is feature-complete for its intended v1.x scope: mainstream SaaS integrations — payments, billing, Connect, tax on custom flows, webhooks (including thin events), and production operator guides.

Not in v1.x scope (maintenance mode; additions only on adopter pull):

• Specialist Stripe families: Identity; Treasury; Issuing; Terminal; Financial Connections; Climate; Sigma; Reporting
• Tax narrow follow-ups: Tax Code lookup (/v1/tax_codes); Tax Transaction list (if Stripe adds the endpoint)

See Scope for boundaries, escape hatches, and how to request coverage. See API Stability for the semver contract.

Docs Ladder

Use the docs in this order:

• README for the repo-level surface map and route-by-intent overview
• Getting Started for first success with a live client and API call
• User Flows & JTBD for "which Stripe path fits my SaaS?"
• Scope for v1.x boundaries and deferred families
• Canonical guides for the surface you will actually ship
• Recipes for compact job-to-primitive bridges
• Webhooks, Production Checklist, Event Debugging, Testing, and Error Handling for runtime truth and support posture

Choose Your Route

• I want first success fast: Getting Started, Payments, Checkout
• I am evaluating recurring billing for a SaaS: User Flows & JTBD, Subscriptions, Customer Portal, Webhooks
• I need usage-based billing and reconciliation: Metering, Webhooks, Testing
• I calculate tax on custom payment flows (not only Checkout/Invoices): Tax, Payments, Testing
• I run a marketplace or platform: Connect, Connect Accounts, Connect Money Movement
• I am hardening ops and support paths: Production Checklist, Error Handling, Testing, Webhooks, Webhooks: Thin Events, Event Debugging

Installation

Add lattice_stripe to your dependencies in mix.exs:

def deps do
  [
    {:lattice_stripe, "~> 1.7"}
  ]
end

Quick Start

LatticeStripe uses Finch for HTTP requests. Add it to your supervision tree in application.ex:

children = [
  {Finch, name: MyApp.Finch}
]

Then create a client and make your first API call:

client = LatticeStripe.Client.new!(
  api_key: "sk_test_...",
  finch: MyApp.Finch
)

{:ok, payment_intent} = LatticeStripe.PaymentIntent.create(client, %{
  "amount" => 2000,
  "currency" => "usd",
  "payment_method" => "pm_card_visa",
  "confirm" => true,
  "automatic_payment_methods" => %{"enabled" => true, "allow_redirects" => "never"}
})

IO.puts("PaymentIntent created: #{payment_intent.id}")

Features

Payments

• Customers, PaymentIntents, SetupIntents, PaymentMethods, Refunds, Checkout Sessions (payment / subscription / setup modes)
• Charge list/search/update/capture for support, audit, and Connect reconciliation — Charge API (PI-first; no create)
• Structured, pattern-matchable errors: :card_error, :authentication_error, :rate_limit_error, :api_error, and more — Guide: Error Handling
• Auto-pagination — stream through large result sets lazily with Elixir Streams
• Guide: Payments

Billing

• Invoices — create, finalize, pay, void, send, list, search
• Credit Notes — preview, create, void, and inspect/stream line items
• Quotes — create, finalize, accept/cancel, inspect/stream line items, and download PDFs
• Subscriptions with lifecycle verbs (cancel, resume, pause_collection, trial settings)
• Subscription Schedules for phased billing with proration guards
• Billing Metering — usage-based billing with Meter, MeterEvent, and MeterEventAdjustment; two-layer idempotency and pre-flight value guards
• Customer Portal — BillingPortal.Session for self-service portal URLs with 4 flow types (subscription_cancel, subscription_update, subscription_update_confirm, payment_method_update) and Inspect masking
• Guide: Subscriptions · Guide: Credit Notes · Guide: Metering · Guide: Tax · Guide: Customer Portal

Operations and diagnostics

• Files and FileLinks — upload files to Stripe, manage shareable file links, and download binary content
• Disputes — retrieve/list, update metadata, stage evidence safely, submit evidence, and close disputes
• Mandates and SetupAttempts — inspect payment authorization state and SetupIntent failure history
• Operator playbooks: Production Checklist · Event Debugging
• Guide: Recipes · Guide: Webhooks · Guide: Webhooks: Thin Events · Guide: Testing
• Full ops guide ladder: Docs Ladder and User Flows & JTBD (Job 7)

Connect

• Connect accounts (Standard, Express, Custom) with onboarding AccountLinks
• Transfers, TransferReversals, Payouts, External Accounts
• Balance + BalanceTransactions for platform-fee reconciliation
• Per-client and per-request stripe_account for platform integrations
• Guide: Connect

Platform

• Pluggable Transport, Json, and RetryStrategy behaviours — bring your own HTTP client
• Automatic retry with exponential backoff, respecting Stripe's Stripe-Should-Retry header
• Automatic idempotency-key generation and safe replay
• Telemetry events for every request, compatible with any monitoring stack
• Phoenix-ready Webhook.Plug snapshot path + thin-event (/v2/events) helpers for fetch-after-verify integration
• Guide: Extending LatticeStripe

Compatibility

Documentation

Full documentation with guides, examples, and API reference is available on HexDocs.

Start here on HexDocs:

• Getting Started
• User Flows & JTBD
• Recipes

Canonical guide clusters:

• Payments and billing primitives: Payments, Checkout, Invoices, Credit Notes, Subscriptions, Customer Portal, Metering, Tax, Charge API
• Connect: Connect, Connect Accounts, Connect Money Movement
• Operations and DX: Webhooks, Webhooks: Thin Events, Production Checklist, Event Debugging, Testing, Error Handling, Client Configuration, Performance, Circuit Breaker, OpenTelemetry, Telemetry, API Stability, Extending LatticeStripe, Cheatsheet

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT — see LICENSE for details.