LatticeStripe.AccountLink (LatticeStripe v1.1.0)

Copy Markdown View Source

Operations on Stripe Connect Account Links — short-lived onboarding URLs.

An Account Link is a single-use URL that hosts Stripe's own Connect onboarding or account-update flow. You send the user to this URL, they complete KYC / account information, and Stripe redirects them back to your return_url (or refresh_url if the link expires or errors).

Usage

{:ok, link} = LatticeStripe.AccountLink.create(client, %{
  "account" => "acct_connected_123",
  "type" => "account_onboarding",
  "refresh_url" => "https://example.com/connect/refresh",
  "return_url" => "https://example.com/connect/return"
})

redirect_user_to(link.url)

Security: the returned URL is a short-lived bearer token

The url field is a bearer token granting the holder access to the connected account's onboarding flow. It expires ~300 seconds after creation. Do not log the URL, do not store it in a database, do not include it in error reports or telemetry payloads. Redirect the user immediately and let the URL expire. If you need a fresh URL, create a new Account Link — they are cheap (Phase 17 T-17-02).

Create-only

Stripe does not expose retrieve, update, delete, or list endpoints for Account Links. This module provides create/3 and create!/3 only.

D-04c decision: no positional type argument

create/3 follows the SDK-wide create(client, params, opts) shape. The type field ("account_onboarding" | "account_update") goes inside params, not as a positional argument. This is Phase 17 D-04c: we rejected a 4-arity create(client, type, params, opts) variant because elevating one field of a multi-field create to a positional argument would break the SDK-wide shape for marginal typo protection on a 2-value enum.

If the "type" key is missing from params, Stripe will return a 400 which surfaces as {:error, %LatticeStripe.Error{type: :invalid_request_error}}. We do NOT client-side validate this (Phase 15 D5 "no fake ergonomics" — let Stripe's own error flow through).

Stripe API Reference

See the Stripe Account Links API.

Summary

Types

t()

A Stripe Connect Account Link.

Functions

create(client, params, opts \\ [])

Creates a new Account Link.

create!(client, params, opts \\ [])

Like create/3 but raises on failure.

Types

t()

@type t() :: %LatticeStripe.AccountLink{
  created: integer() | nil,
  expires_at: integer() | nil,
  extra: map(),
  object: String.t(),
  url: String.t() | nil
}

A Stripe Connect Account Link.

Functions

create(client, params, opts \\ [])

@spec create(LatticeStripe.Client.t(), map(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Creates a new Account Link.

Sends POST /v1/account_links. Required params:

  • "account" — Connected account ID ("acct_...")
  • "type" — "account_onboarding" or "account_update"
  • "refresh_url" — URL Stripe redirects to if the link expires
  • "return_url" — URL Stripe redirects to on completion

create!(client, params, opts \\ [])

@spec create!(LatticeStripe.Client.t(), map(), keyword()) :: t()

Like create/3 but raises on failure.