MishkaPay.Checkout (Mishka Pay v0.0.1)

Copy Markdown View Source

A checkout: what the buyer pays for and where they come back to, then the provider's answer. A guarded_struct; MishkaPay.checkout/1 builds it from a map and hands it to the provider.

Read back with MishkaPay.fetch_checkout/3, :items are what the buyer bought, with their provider price and product ids; :phone_number, :field_values (each field's key to the buyer's answer) and :terms_accepted are what the buyer gave.

What the caller gives:

  • :provider and :tenant: which provider, with whose keys (MishkaPay.Credentials).
  • :items: one or more MishkaPay.Price, all in one currency; none in mode: :setup.
  • :ui_mode: :hosted (the default) sends the buyer to the provider's page; :embedded shows the provider's form inside the site's own page, and needs :embedded_checkout.
  • :success_url, :cancel_url: with :hosted, where the buyer is sent after paying or giving up; https, or http on localhost. Both are required.
  • :return_url: with :embedded, the one address the buyer comes back to after paying, or after a payment method's own page. It is required, and replaces the two above. At Stripe, {CHECKOUT_SESSION_ID} in it becomes the checkout's id.
  • :customer: an optional buyer: %{id: "cus_..."} for a customer the provider keeps, or %{email: "..."} to fill in a new buyer's email; one or the other (MishkaPay.Customer).
  • :reference: the caller's own id for this sale, such as an order id. The provider keeps it, it comes back on the payment, and it makes the request's idempotency key, so the same reference never opens two checkouts.
  • :owner: who the sale is for in the caller's app, such as the signed-in user's id. The provider keeps it on the payment or the subscription, and it comes back on either (MishkaPay.Payment, MishkaPay.Subscription), so access can be given to that user. The Ash layer fills it from the actor (MishkaPay.Ash.Resource).
  • :merchant_of_record: true asks the provider to sell as the merchant of record (it collects and files the tax, as Stripe Managed Payments does), false asks it not to; left out, the provider's account default applies. Each price then needs its :tax_code.
  • :metadata: extra pairs kept with the checkout, string keys to string values; each provider has its own limits on how many and how long.
  • :mode: :payment (the default) sells once; :subscription starts a subscription, so every item needs a recurring price (:interval, or a provider price :id) and the provider needs :subscription. A one-time checkout refuses a recurring price. :setup saves a payment method without charging (below).
  • :trial_days: with :subscription, how many days the buyer uses it before the first charge.
  • :discounts: coupons or promotion codes the checkout applies by itself (MishkaPay.Checkout.Discounts), or :allow_promotion_codes: true lets the buyer type a code. One or the other.
  • :automatic_tax: true has the provider count the tax from the buyer's address (Stripe Tax); each price then needs its :tax_code.
  • :customer_creation: in a one-time or setup checkout, :always makes a provider customer for the buyer, :if_required only when the provider needs one.
  • :locale: the language of the provider's page ("de", "auto").
  • :terms: true makes the buyer accept the site's terms of service before paying (the terms page is set in the provider's account). It helps when a buyer later disputes a sale.
  • :phone: true asks the buyer for a phone number.
  • :fields: up to three questions the page asks, each a MishkaPay.Checkout.Fields; the answers come back in :field_values.
  • :card_required: with :subscription and a trial, false starts the trial without a card; the provider asks for one before the first charge.
  • :billing_mode: with :subscription, how the provider counts prorations and bills: :flexible (the default, Stripe's recommended mode) or :classic (its older counting). Left out, the tenant's :billing_mode (MishkaPay.Credentials) applies, else :flexible. It is set once, when the subscription is made.
  • :proration_discounts: with the flexible billing mode, how a bill shows a proration of a discounted price: :itemized (the default, Stripe's recommended way: the full amount and the discount, as on any other line) or :included (the amount after the discount, with a discount of zero). Left out, the tenant's :proration_discounts applies, else :itemized.
  • :description: the payment's, the subscription's or the setup's description at the provider.
  • :statement_suffix: up to 22 letters, digits or spaces added to the line on the buyer's card statement, such as an order number.
  • :submit_type: the word on the pay button of a one-time checkout: :pay, :book, :donate or :auto.
  • :expires_at: when the checkout stops taking payment; the provider has its own limits (Stripe: 30 minutes to 24 hours from now). MishkaPay.expire_checkout/3 ends it at once.
  • :billing_address: :auto (only when needed) or :required.
  • :tax_id_collection: true lets a business buyer give its tax id.
  • :invoice: in a one-time checkout, true makes an invoice for the payment, which the provider can email with the receipt; a subscription makes its own invoices.
  • :capture: in a one-time checkout, :manual only holds the money on the buyer's card: the payment waits as :authorized until MishkaPay.capture_payment/4 takes it, all or part, or MishkaPay.cancel_payment/3 lets it go. Needs :capture. :automatic (the default) takes it at once, the provider's recommended way (Stripe's automatic_async); :automatic_sync takes it at once the older way, where the provider still has one (Stripe's automatic, which answers only once the money is taken). Card holds end on their own after some days (Stripe: 7 by default).
  • :shipping_countries: two-letter country codes (["NL", "DE"]): the page asks the buyer for a shipping address in one of them. A subscription may ask for one too.
  • :shipping_rates: in a one-time checkout, the ways to ship the buyer picks from: a rate the provider keeps by its id ("shr_...", MishkaPay.create_shipping_rate/1), or a new one as a map (%{name: "Post", amount: %{amount: "4.95", currency: "EUR"}, min_days: 2, max_days: 5}, see MishkaPay.ShippingRate) in the items' currency. The provider needs :shipping. A merchant of record (:merchant_of_record) sells no shipped goods, so shipping goes only with it off.

On a platform of sellers (the provider needs :connect):

  • :destination: the seller's connected account the money goes to; the platform takes the sale and the provider moves it on (a destination charge).
  • :on_behalf_of: the connected account that is the seller of record: its country and statement name apply, and its fees. Usually the same account as :destination.
  • :application_fee: in a one-time checkout, the platform's cut as money, in the items' currency; with :destination it stays with the platform, and with a site's keys that name a connected account (a direct charge) it goes to the platform.
  • :application_fee_percent: in a subscription, the platform's cut of each bill, above 0 and up to 100, two decimals at most.

None of them goes with mode: :setup.

mode: :setup saves a payment method for later and charges nothing; the provider needs :payment_method. It takes no :items, and needs a :currency ("usd"), which decides the payment methods the page offers. A buyer given by customer: %{id: ...} keeps the card; without one the provider makes a customer for it. Read back, the checkout brings :setup_intent_id, :payment_method_id and the customer's id under :customer. The options of a sale (:trial_days, :discounts, :allow_promotion_codes, :automatic_tax, :merchant_of_record, :invoice, :submit_type, :statement_suffix, :card_required) are refused in setup mode.

A provider refuses an option it cannot honour (MishkaPay.Errors.Unsupported) rather than leaving it out. Which payment methods a Stripe checkout offers is set in the Stripe Dashboard.

What the provider fills in:

  • :id: the provider's id of the checkout (cs_... at Stripe).
  • :url: the page to send the buyer to, with :hosted.
  • :client_secret: with :embedded, what the site's page gives the provider's script to show the form (Stripe.js initEmbeddedCheckout). Send it only to that buyer's browser.
  • :status: :open, :complete or :expired.
  • :payment_id: the payment it made, once there is one (a one-time checkout).
  • :setup_intent_id, :payment_method_id: in setup mode, the setup it made and the payment method it saved, once the buyer is done (MishkaPay.fetch_payment_method/3).
  • :subscription_id: the subscription it started, once there is one.
  • :invoice_id: the invoice it made, with invoice: true, once paid.
  • :payment_link_id: the payment link the buyer came from (MishkaPay.PaymentLink).
  • :amount_total, :amount_tax, :amount_discount: what the buyer pays in all, the tax in it and the discount taken off, as Money, once the provider has counted them (the tax may change as the buyer fills in an address).
  • :shipping_address: where the buyer asked it shipped, a MishkaPay.Address with the recipient's :name; :amount_shipping, what the chosen rate costs, and :shipping_rate_id, which rate it was.

Discounts

Each of :discounts is a MishkaPay.Checkout.Discounts, a subfield of this struct: a coupon (%{coupon_id: "SPRING"}) or a promotion code (`%{promotion_code_id: "promo..."}), one of them. To let the buyer type a code instead, a checkout setsallow_promotion_codes: true`; a checkout does one or the other.

Fields

Each of :fields is a MishkaPay.Checkout.Fields, a sub_field of this struct: a question the provider's page asks the buyer, such as "Name on the certificate" or "Which site is this for" (Stripe takes three). The answers come back on the checkout read again, in its :field_values, each field's key to the buyer's answer as the provider sent it.

  • :key: the caller's own name for it, letters and digits, up to 200 characters.
  • :label: what the buyer reads, up to 50 characters.
  • :type: :text (the default), :numeric, or :dropdown with its :options, from one to 200, each a MishkaPay.Checkout.Fields.Options (%{value: "pro", label: "Pro"}).
  • :optional: true lets the buyer leave it empty.

Shipping rates

:shipping_rates is a conditional field: each entry is either a rate id string the provider keeps ("shr_..."), kept as the string, or a map built into a MishkaPay.ShippingRate.

Summary

Types

t()

The struct that builder/1 returns.

Functions

Whether attrs (a caller's map) asks for proration discounts only with the flexible billing mode: :proration_discounts with billing_mode: :classic is an error on :proration_discounts. Checkouts and subscription schedules check it before they are built.

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

Whether built checkout has the pages its :ui_mode needs: :success_url and :cancel_url when hosted, :return_url when embedded. MishkaPay.checkout/1 checks it after the build, so a page given and refused is reported once, by its own field.

Types

t()

@type t() :: %MishkaPay.Checkout{
  allow_promotion_codes: boolean() | nil,
  amount_discount: Money.t() | nil,
  amount_shipping: Money.t() | nil,
  amount_tax: Money.t() | nil,
  amount_total: Money.t() | nil,
  application_fee: Money.t() | nil,
  application_fee_percent: Decimal.t() | nil,
  automatic_tax: boolean() | nil,
  billing_address: (:auto | :required) | nil,
  billing_mode: (:flexible | :classic) | nil,
  cancel_url: String.t() | nil,
  capture: (:automatic | :automatic_sync | :manual) | nil,
  card_required: boolean() | nil,
  client_secret: String.t() | nil,
  currency: atom() | nil,
  customer: MishkaPay.Customer.t() | nil,
  customer_creation: (:always | :if_required) | nil,
  description: String.t() | nil,
  destination: String.t() | nil,
  discounts: [MishkaPay.Checkout.Discounts.t()] | nil,
  expires_at: DateTime.t() | nil,
  field_values: map() | nil,
  fields: [MishkaPay.Checkout.Fields.t()] | nil,
  id: String.t() | nil,
  invoice: boolean() | nil,
  invoice_id: String.t() | nil,
  items: [MishkaPay.Price.t()] | nil,
  locale: String.t() | nil,
  merchant_of_record: boolean() | nil,
  metadata: map() | nil,
  mode: (:payment | :subscription | :setup) | nil,
  on_behalf_of: String.t() | nil,
  owner: String.t() | nil,
  payment_id: String.t() | nil,
  payment_link_id: String.t() | nil,
  payment_method_id: String.t() | nil,
  phone: boolean() | nil,
  phone_number: String.t() | nil,
  proration_discounts: (:itemized | :included) | nil,
  provider: String.t(),
  reference: String.t() | nil,
  return_url: String.t() | nil,
  setup_intent_id: String.t() | nil,
  shipping_address: MishkaPay.Address.t() | nil,
  shipping_countries: list() | nil,
  shipping_rate_id: String.t() | nil,
  shipping_rates: [String.t() | MishkaPay.ShippingRate.t()] | nil,
  statement_suffix: String.t() | nil,
  status: (:open | :complete | :expired) | nil,
  submit_type: (:auto | :pay | :book | :donate) | nil,
  subscription_id: String.t() | nil,
  success_url: String.t() | nil,
  tax_id_collection: boolean() | nil,
  tenant: term() | nil,
  terms: boolean() | nil,
  terms_accepted: boolean() | nil,
  trial_days: pos_integer() | nil,
  ui_mode: (:hosted | :embedded) | nil,
  url: String.t() | nil
}

The struct that builder/1 returns.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)
:tenantterm() | nilno
:items[MishkaPay.Price.t()] | nilnovalidate(not_nil_value, list)
:ui_mode:hosted | :embedded | nilno:hostedvalidate(not_nil_value, enum=Atom[hosted::embedded])<br>validator {MishkaPay.Checkout, :ui_mode}
:success_urlString.t() | nilnosanitize(trim) validate(string)<br>validator {MishkaPay.Checkout, :return_url}
:cancel_urlString.t() | nilnosanitize(trim) validate(string)<br>validator {MishkaPay.Checkout, :return_url}
:return_urlString.t() | nilnosanitize(trim) validate(string)<br>validator {MishkaPay.Checkout, :return_url}
:capture:automatic | :automatic_sync | :manual | nilnovalidate(enum=Atom[automatic::automatic_sync::manual])<br>validator {MishkaPay.Checkout, :capture}
:customerMishkaPay.Customer.t() | nilno
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:ownerString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:merchant_of_recordboolean() | nilnovalidate(boolean)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}
:idString.t() | nilnovalidate(string)
:urlString.t() | nilnovalidate(string)
:client_secretString.t() | nilnovalidate(string)
:status:open | :complete | :expired | nilnovalidate(enum=Atom[open::complete::expired])
:mode:payment | :subscription | :setup | nilno:paymentvalidate(not_nil_value, enum=Atom[payment::subscription::setup])<br>validator {MishkaPay.Checkout, :mode}
:currencyatom() | nilnovalidator {MishkaPay.Money, :currency_field}
:trial_dayspos_integer() | nilnovalidate(integer, min_len=1)
:discounts[MishkaPay.Checkout.Discounts.t()] | nilnovalidate(list)
:allow_promotion_codesboolean() | nilnovalidate(boolean)
:automatic_taxboolean() | nilnovalidate(boolean)
:customer_creation:always | :if_required | nilnovalidate(enum=Atom[always::if_required])<br>validator {MishkaPay.Checkout, :customer_creation}
:localeString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=10)
:expires_atDateTime.t() | nilnovalidate(struct)<br>validator {MishkaPay.Checkout, :later}
:billing_address:auto | :required | nilnovalidate(enum=Atom[auto::required])<br>validator {MishkaPay.Checkout, :billing_address}
:tax_id_collectionboolean() | nilnovalidate(boolean)
:termsboolean() | nilnovalidate(boolean)
:phoneboolean() | nilnovalidate(boolean)
:fields[MishkaPay.Checkout.Fields.t()] | nilnovalidate(list, max_len=3)
:card_requiredboolean() | nilnovalidate(boolean)
:billing_mode:flexible | :classic | nilnovalidate(enum=Atom[flexible::classic])<br>validator {MishkaPay.Checkout, :billing_mode}
:proration_discounts:itemized | :included | nilnovalidate(enum=Atom[itemized::included])<br>validator {MishkaPay.Checkout, :proration_discounts}
:descriptionString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=500)
:statement_suffixString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=22, regex=^[A-Za-z0-9 ]+$)
:submit_type:auto | :pay | :book | :donate | nilnovalidate(enum=Atom[auto::pay::book::donate])<br>validator {MishkaPay.Checkout, :submit_type}
:phone_numberString.t() | nilnovalidate(string)
:field_valuesmap() | nilnovalidate(map)
:terms_acceptedboolean() | nilnovalidate(boolean)
:invoiceboolean() | nilnovalidate(boolean)
:invoice_idString.t() | nilnovalidate(string)
:shipping_countrieslist() | nilnosanitize(each=[trim, upcase]) validate(list, not_empty, each=[string, regex=\A[A-Z]{2}\z])
:shipping_rates[String.t() | MishkaPay.ShippingRate.t()] | nilnovalidate(list)
:shipping_addressMishkaPay.Address.t() | nilno
:amount_shippingMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:shipping_rate_idString.t() | nilnovalidate(string)
:payment_link_idString.t() | nilnovalidate(string)
:application_feeMoney.t() | nilnovalidator {MishkaPay.Refund, :amount}
:application_fee_percentDecimal.t() | nilnovalidator {MishkaPay.Checkout, :fee_percent}
:destinationString.t() | nilnosanitize(trim) validate(string, not_empty)
:on_behalf_ofString.t() | nilnosanitize(trim) validate(string, not_empty)
:payment_idString.t() | nilnovalidate(string)
:setup_intent_idString.t() | nilnovalidate(string)
:payment_method_idString.t() | nilnovalidate(string)
:subscription_idString.t() | nilnovalidate(string)
:amount_totalMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:amount_taxMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:amount_discountMoney.t() | nilnovalidator {MishkaPay.Money, :field}

Functions

billing(attrs)

@spec billing(map()) :: {:ok, map()} | {:error, map()}

Whether attrs (a caller's map) asks for proration discounts only with the flexible billing mode: :proration_discounts with billing_mode: :classic is an error on :proration_discounts. Checkouts and subscription schedules check it before they are built.

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

keys()

keys(field)

pages(checkout)

@spec pages(t()) :: :ok | {:error, Splode.Error.t()}

Whether built checkout has the pages its :ui_mode needs: :success_url and :cancel_url when hosted, :return_url when embedded. MishkaPay.checkout/1 checks it after the build, so a page given and refused is reported once, by its own field.