A page that sells catalog prices to anyone who opens it (https://buy.stripe.com/... at
Stripe), made once and put on a website, in an email or a QR code. A guarded_struct. Each buyer
who opens it gets their own checkout, so its sales come in like any other: checkout.session
and payment_intent webhooks, read with MishkaPay.fetch_payment/3.
Made with MishkaPay.create_payment_link/1, read with MishkaPay.fetch_payment_link/3 and
MishkaPay.list_payment_links/3, turned off or on again with MishkaPay.update_payment_link/1
(active: false). A link cannot be deleted; a turned-off link refuses buyers.
What the caller gives:
:provider,:tenant: which provider, with whose keys.:items: catalog prices by id with their quantity ([%{id: "price_...", quantity: 1}]); a recurring price makes it a subscription link.:success_url: where the buyer goes after paying; left out, the provider shows its own thank-you page.:max_purchases: how many purchases it takes before it turns itself off:1for a one-time link, any count for a limited one; left out, no limit.:inactive_message: what a buyer reads on it once it is off or used up.:quantity_min,:quantity_max: let the buyer change how many they take, within these.:allow_promotion_codes,:automatic_tax,:invoice,:trial_days,:customer_creation,:billing_address,:tax_id_collection,:merchant_of_record: as on aMishkaPay.Checkout; the tenant's settings give:automatic_taxand:merchant_of_recordwhen the link does not. A provider that is the merchant of record (Stripe Managed Payments) always makes an invoice.:metadata: extra pairs, string keys to string values.
Every option left out is the provider's own default.
What the provider fills in: :id, :url, :active, :purchases (how many so far, with
:max_purchases), :created_at.
url/2 adds one buyer's details to the link's address: reference: (the host's order or user
id, which comes back as the checkout's :reference), email:, locale: and promotion_code:.
Summary
Functions
A sample %MishkaPay.PaymentLink{} populated from defaults + type-based fallbacks.
The link's address for one buyer: reference: (letters, digits, _ and -, at most 200),
email:, locale: and promotion_code: are filled in on the provider's page. Raises
ArgumentError for a reference the provider would drop.
Types
@type t() :: %MishkaPay.PaymentLink{ active: boolean() | nil, allow_promotion_codes: boolean() | nil, automatic_tax: boolean() | nil, billing_address: (:auto | :required) | nil, created_at: DateTime.t() | nil, customer_creation: (:always | :if_required) | nil, id: String.t() | nil, inactive_message: String.t() | nil, invoice: boolean() | nil, items: [MishkaPay.Price.t()] | nil, max_purchases: pos_integer() | nil, merchant_of_record: boolean() | nil, metadata: map() | nil, provider: String.t() | nil, purchases: non_neg_integer() | nil, quantity_max: pos_integer() | nil, quantity_min: pos_integer() | nil, success_url: String.t() | nil, tax_id_collection: boolean() | nil, tenant: term() | nil, trial_days: pos_integer() | nil, url: String.t() | nil }
The struct that builder/1 returns.
| Field | Type | Required | Default | Description | Derives |
|---|---|---|---|---|---|
:provider | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:tenant | term() | nil | no | |||
:id | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:url | String.t() | nil | no | validate(string) | ||
:active | boolean() | nil | no | validate(boolean) | ||
:items | [MishkaPay.Price.t()] | nil | no | validate(list) | ||
:success_url | String.t() | nil | no | sanitize(trim) validate(string)<br>validator {MishkaPay.Checkout, :return_url} | ||
:allow_promotion_codes | boolean() | nil | no | validate(boolean) | ||
:automatic_tax | boolean() | nil | no | validate(boolean) | ||
:invoice | boolean() | nil | no | validate(boolean) | ||
:trial_days | pos_integer() | nil | no | validate(integer, min_len=1) | ||
:max_purchases | pos_integer() | nil | no | validate(integer, min_len=1) | ||
:purchases | non_neg_integer() | nil | no | validate(integer) | ||
:inactive_message | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=500) | ||
:quantity_min | pos_integer() | nil | no | validate(integer, min_len=1, max_len=999999) | ||
:quantity_max | pos_integer() | nil | no | validate(integer, min_len=1, max_len=999999) | ||
:customer_creation | :always | :if_required | nil | no | validate(enum=Atom[always::if_required])<br>validator {MishkaPay.Checkout, :customer_creation} | ||
:billing_address | :auto | :required | nil | no | validate(enum=Atom[auto::required])<br>validator {MishkaPay.Checkout, :billing_address} | ||
:tax_id_collection | boolean() | nil | no | validate(boolean) | ||
:merchant_of_record | boolean() | nil | no | validate(boolean) | ||
:metadata | map() | nil | no | %{} | validate(map)<br>validator {MishkaPay.Checkout, :metadata} | |
:created_at | DateTime.t() | nil | no | validate(struct) |
Functions
A sample %MishkaPay.PaymentLink{} populated from defaults + type-based fallbacks.
The link's address for one buyer: reference: (letters, digits, _ and -, at most 200),
email:, locale: and promotion_code: are filled in on the provider's page. Raises
ArgumentError for a reference the provider would drop.
MishkaPay.PaymentLink.url(link, reference: "order-42", email: "ava@example.com")
#=> "https://buy.stripe.com/test_...?client_reference_id=order-42&prefilled_email=..."