Payments

This guide walks through the complete payment lifecycle in LatticeStripe — from creating a customer to confirming a payment to issuing refunds. For an overview of Stripe's payment model, see the Stripe Payments documentation.

Creating a Customer

Customers let you associate payments, subscriptions, and payment methods with a person or business. Creating a customer before charging is recommended — it enables features like saving payment methods and listing past charges.

{:ok, customer} = LatticeStripe.Customer.create(client, %{
  "email" => "alice@example.com",
  "name" => "Alice Johnson",
  "phone" => "+1-555-123-4567",
  "metadata" => %{
    "user_id" => "usr_123",
    "plan" => "pro"
  }
})

IO.puts("Created customer: #{customer.id}")
# Created customer: cus_OtVFqSomeStripeId

metadata is a hash of up to 50 key/value string pairs. Use it to link Stripe objects back to your own data model — it shows up in the Stripe Dashboard and is returned on every fetch.

Retrieving and Updating Customers

# Retrieve a customer by ID
{:ok, customer} = LatticeStripe.Customer.retrieve(client, "cus_OtVFqSomeStripeId")

# Update the customer's name and metadata
{:ok, updated} = LatticeStripe.Customer.update(client, customer.id, %{
  "name" => "Alice Smith",
  "metadata" => %{"plan" => "enterprise"}
})

Creating a PaymentIntent

A PaymentIntent represents your intent to collect payment from a customer. It tracks the lifecycle of the payment and handles retries, 3D Secure authentication, and more.

{:ok, intent} = LatticeStripe.PaymentIntent.create(client, %{
  "amount" => 4999,
  "currency" => "usd",
  "customer" => customer.id,
  "description" => "Pro plan subscription",
  "metadata" => %{"order_id" => "ord_456"}
})

IO.puts("PaymentIntent #{intent.id} — status: #{intent.status}")
# PaymentIntent pi_3OzqKZ2eZvKYlo2C1FRzQc8s — status: requires_payment_method

Amount is always in the smallest currency unit. For USD, that's cents: 4999 = $49.99. For JPY (zero-decimal currency), 4999 = ¥4,999.

Automatic vs. Manual Confirmation

By default, Stripe expects you to confirm the PaymentIntent from your client-side (frontend) code using Stripe.js. For server-side confirmation (e.g., backend-only flows or Stripe Connect), use confirmation_method: "manual":

{:ok, intent} = LatticeStripe.PaymentIntent.create(client, %{
  "amount" => 4999,
  "currency" => "usd",
  "confirmation_method" => "manual",
  "payment_method" => "pm_card_visa"
})

Confirming a PaymentIntent

For manually-confirmed PaymentIntents, call confirm/3 to attempt payment:

case LatticeStripe.PaymentIntent.confirm(client, intent.id, %{
  "payment_method" => "pm_card_visa"
}) do
  {:ok, confirmed} ->
    case confirmed.status do
      "succeeded" ->
        IO.puts("Payment succeeded!")

      "requires_action" ->
        IO.puts("3D Secure required — redirect to: #{confirmed.next_action["redirect_to_url"]["url"]}")

      other ->
        IO.puts("Unexpected status: #{other}")
    end

  {:error, %LatticeStripe.Error{type: :card_error} = err} ->
    IO.puts("Card declined: #{err.message}")
    IO.puts("Decline code: #{err.decline_code}")
end

The PaymentIntent status machine:

requires_payment_method → attach a payment method
requires_confirmation → call confirm/3
requires_action → customer must complete authentication (e.g., 3D Secure)
processing → payment is being processed (async)
succeeded → payment successful
canceled → terminal state

Capturing a PaymentIntent (Manual Capture)

If you need to authorize a payment now but capture funds later — for example, when fulfillment happens after checkout — create the PaymentIntent with capture_method: "manual":

# Step 1: Authorize (hold funds on the card, don't capture yet)
{:ok, intent} = LatticeStripe.PaymentIntent.create(client, %{
  "amount" => 4999,
  "currency" => "usd",
  "payment_method" => "pm_card_visa",
  "capture_method" => "manual",
  "confirm" => true
})

IO.puts("Authorized: #{intent.status}")
# Authorized: requires_capture

# (Later, once the order ships or service is fulfilled)

# Step 2: Capture the authorized funds
{:ok, captured} = LatticeStripe.PaymentIntent.capture(client, intent.id)
IO.puts("Captured: #{captured.status}")
# Captured: succeeded

You can also capture a partial amount:

{:ok, captured} = LatticeStripe.PaymentIntent.capture(client, intent.id, %{
  "amount_to_capture" => 2500  # Capture only $25.00 instead of $49.99
})

Uncaptured authorizations automatically expire after 7 days (or 2 days for some card networks). See Stripe's capture docs.

Canceling a PaymentIntent

Cancel a PaymentIntent that hasn't succeeded or been captured yet:

{:ok, canceled} = LatticeStripe.PaymentIntent.cancel(client, intent.id, %{
  "cancellation_reason" => "abandoned"
})

IO.puts("Status: #{canceled.status}")
# Status: canceled

Valid cancellation reasons: "duplicate", "fraudulent", "requested_by_customer", "abandoned". The canceled status is terminal — you cannot revive a canceled PaymentIntent.

Listing and Searching

Listing with Filters

# List recent PaymentIntents for a specific customer
{:ok, resp} = LatticeStripe.PaymentIntent.list(client, %{
  "customer" => customer.id,
  "limit" => 10
})

intents = resp.data.data
IO.puts("Found #{length(intents)} PaymentIntents")

Auto-Pagination with Streams

For large datasets, use stream!/2 to lazily auto-paginate through all results without loading everything into memory at once:

# Process all succeeded PaymentIntents in the last 30 days
client
|> LatticeStripe.PaymentIntent.stream!(%{"created" => %{"gte" => thirty_days_ago}})
|> Stream.filter(fn intent -> intent.status == "succeeded" end)
|> Stream.map(fn intent -> intent.amount end)
|> Enum.sum()
|> then(fn total -> IO.puts("Total revenue: $#{total / 100}") end)

stream!/2 fetches pages lazily — it only makes an HTTP request when the stream needs more items. This is memory-efficient for exporting large datasets.

Search

Use search/2 for full-text search across PaymentIntents:

{:ok, resp} = LatticeStripe.PaymentIntent.search(client, %{
  "query" => "metadata['order_id']:'ord_456'"
})

results = resp.data.data

Note: Stripe's Search API has eventual consistency. Newly created objects may not appear in search results immediately. For real-time lookups, use list/3 with filters or retrieve/3 by ID. See Stripe Search docs.

Refunding a Payment

To return funds to a customer, create a Refund referencing the original PaymentIntent:

Full Refund

{:ok, refund} = LatticeStripe.Refund.create(client, %{
  "payment_intent" => intent.id,
  "reason" => "requested_by_customer"
})

IO.puts("Refund #{refund.id} — status: #{refund.status}")
# Refund re_3OzqKZ2eZvKYlo2C1FRzQc8s — status: succeeded

Partial Refund

Specify an amount to refund only part of the original charge:

# Refund $10.00 of a $49.99 payment
{:ok, refund} = LatticeStripe.Refund.create(client, %{
  "payment_intent" => intent.id,
  "amount" => 1000
})

Refund Reasons

Valid reasons: "duplicate", "fraudulent", "requested_by_customer". The reason affects how the refund appears in the Stripe Dashboard and any reporting. Omitting the reason is also valid.

Listing Refunds

{:ok, resp} = LatticeStripe.Refund.list(client, %{
  "payment_intent" => intent.id
})

refunds = resp.data.data

Working with Idempotency Keys

Idempotency keys make retries safe. If a network failure causes you to lose the response from a create call, you can retry with the same key — Stripe will return the original result rather than creating a duplicate.

LatticeStripe automatically generates a UUID-based idempotency key for every POST request. The key is reused across all retry attempts for that request, so automatic retries are always safe.

For operations tied to your own IDs — where you want to guarantee "this specific payment was created exactly once" — provide your own key:

{:ok, intent} = LatticeStripe.PaymentIntent.create(client, %{
  "amount" => 4999,
  "currency" => "usd",
  "customer" => customer.id
},
  idempotency_key: "payment-intent-order-#{order.id}"
)

If you call this again with the same order.id (e.g., after a server restart), Stripe returns the original PaymentIntent rather than creating a new one — you can't accidentally double-charge a customer.

Key uniqueness rules:

Keys must be unique per API endpoint (not globally)
Reusing a key with different parameters returns a 409 error
Keys expire after 24 hours — after that, a new request with the same key starts fresh
For automatic retries, the same key is reused — don't generate a new key per attempt

Common Pitfalls

Amount is in the smallest currency unit (cents for USD). 4999 means $49.99, not $4,999. Always think in cents when working with Stripe. This is the single most common mistake when integrating Stripe for the first time.

PaymentIntent status machine — transitions only go one direction. You can't capture a canceled PaymentIntent. You can't confirm an already-succeeded one. Always check intent.status before performing an action, and handle the case where the intent is in an unexpected state.

Idempotency keys must be unique per distinct request. If you want to create two different payments for the same customer on the same order, use different keys (e.g., include a line item ID). Reusing a key with different params returns a 409 conflict, not a new payment.

Automatic confirmation vs. manual confirmation. By default, Stripe uses "automatic" confirmation, which expects your frontend (Stripe.js) to confirm the payment. If you're building a server-side-only flow, set confirmation_method: "manual" so you can confirm from your backend. Getting this wrong leads to requires_confirmation status that never resolves.

Search API has eventual consistency. Newly created objects may not appear in search results for up to a few seconds. Don't use search for real-time workflows — use retrieve/3 or list/3 with filters instead. See Stripe's search documentation for consistency guarantees.

← Previous Page Client Configuration

Next Page → Checkout