MishkaPay.PaymentLink (Mishka Pay v0.0.1)

Copy Markdown View Source

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: 1 for 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 a MishkaPay.Checkout; the tenant's settings give :automatic_tax and :merchant_of_record when 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

Types

t()

The struct that builder/1 returns.

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

t()

@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.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t() | nilnosanitize(trim) validate(string, not_empty)
:tenantterm() | nilno
:idString.t() | nilnosanitize(trim) validate(string, not_empty)
:urlString.t() | nilnovalidate(string)
:activeboolean() | nilnovalidate(boolean)
:items[MishkaPay.Price.t()] | nilnovalidate(list)
:success_urlString.t() | nilnosanitize(trim) validate(string)<br>validator {MishkaPay.Checkout, :return_url}
:allow_promotion_codesboolean() | nilnovalidate(boolean)
:automatic_taxboolean() | nilnovalidate(boolean)
:invoiceboolean() | nilnovalidate(boolean)
:trial_dayspos_integer() | nilnovalidate(integer, min_len=1)
:max_purchasespos_integer() | nilnovalidate(integer, min_len=1)
:purchasesnon_neg_integer() | nilnovalidate(integer)
:inactive_messageString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=500)
:quantity_minpos_integer() | nilnovalidate(integer, min_len=1, max_len=999999)
:quantity_maxpos_integer() | nilnovalidate(integer, min_len=1, max_len=999999)
:customer_creation:always | :if_required | nilnovalidate(enum=Atom[always::if_required])<br>validator {MishkaPay.Checkout, :customer_creation}
:billing_address:auto | :required | nilnovalidate(enum=Atom[auto::required])<br>validator {MishkaPay.Checkout, :billing_address}
:tax_id_collectionboolean() | nilnovalidate(boolean)
:merchant_of_recordboolean() | nilnovalidate(boolean)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}
:created_atDateTime.t() | nilnovalidate(struct)

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

A sample %MishkaPay.PaymentLink{} populated from defaults + type-based fallbacks.

keys()

keys(field)

url(payment_link, opts \\ [])

@spec url(t(), keyword()) :: String.t()

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=..."