# `MishkaPay.Checkout`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/checkout.ex#L5)

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 sub_field 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 sets `allow_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`.

# `t`

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

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:tenant` | `term()` \| `nil` | no |  |  |  |
| `:items` | [`[MishkaPay.Price.t()]`](`t:MishkaPay.Price.t/0`) \| `nil` | no |  |  | `validate(not_nil_value, list)` |
| `:ui_mode` | `:hosted` \| `:embedded` \| `nil` | no | `:hosted` |  | `validate(not_nil_value, enum=Atom[hosted::embedded])`<br>validator `{MishkaPay.Checkout, :ui_mode}` |
| `:success_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string)`<br>validator `{MishkaPay.Checkout, :return_url}` |
| `:cancel_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string)`<br>validator `{MishkaPay.Checkout, :return_url}` |
| `:return_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string)`<br>validator `{MishkaPay.Checkout, :return_url}` |
| `:capture` | `:automatic` \| `:automatic_sync` \| `:manual` \| `nil` | no |  |  | `validate(enum=Atom[automatic::automatic_sync::manual])`<br>validator `{MishkaPay.Checkout, :capture}` |
| `:customer` | [`MishkaPay.Customer.t()`](`t:MishkaPay.Customer.t/0`) \| `nil` | no |  |  |  |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:owner` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:merchant_of_record` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:url` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:client_secret` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:status` | `:open` \| `:complete` \| `:expired` \| `nil` | no |  |  | `validate(enum=Atom[open::complete::expired])` |
| `:mode` | `:payment` \| `:subscription` \| `:setup` \| `nil` | no | `:payment` |  | `validate(not_nil_value, enum=Atom[payment::subscription::setup])`<br>validator `{MishkaPay.Checkout, :mode}` |
| `:currency` | `atom()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :currency_field}` |
| `:trial_days` | `pos_integer()` \| `nil` | no |  |  | `validate(integer, min_len=1)` |
| `:discounts` | [`[MishkaPay.Checkout.Discounts.t()]`](`t:MishkaPay.Checkout.Discounts.t/0`) \| `nil` | no |  |  | `validate(list)` |
| `:allow_promotion_codes` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:automatic_tax` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:customer_creation` | `:always` \| `:if_required` \| `nil` | no |  |  | `validate(enum=Atom[always::if_required])`<br>validator `{MishkaPay.Checkout, :customer_creation}` |
| `:locale` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=10)` |
| `:expires_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)`<br>validator `{MishkaPay.Checkout, :later}` |
| `: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)` |
| `:terms` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:phone` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:fields` | [`[MishkaPay.Checkout.Fields.t()]`](`t:MishkaPay.Checkout.Fields.t/0`) \| `nil` | no |  |  | `validate(list, max_len=3)` |
| `:card_required` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:billing_mode` | `:flexible` \| `:classic` \| `nil` | no |  |  | `validate(enum=Atom[flexible::classic])`<br>validator `{MishkaPay.Checkout, :billing_mode}` |
| `:proration_discounts` | `:itemized` \| `:included` \| `nil` | no |  |  | `validate(enum=Atom[itemized::included])`<br>validator `{MishkaPay.Checkout, :proration_discounts}` |
| `:description` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=500)` |
| `:statement_suffix` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=22, regex=^[A-Za-z0-9 ]+$)` |
| `:submit_type` | `:auto` \| `:pay` \| `:book` \| `:donate` \| `nil` | no |  |  | `validate(enum=Atom[auto::pay::book::donate])`<br>validator `{MishkaPay.Checkout, :submit_type}` |
| `:phone_number` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:field_values` | `map()` \| `nil` | no |  |  | `validate(map)` |
| `:terms_accepted` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:invoice` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:invoice_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:shipping_countries` | `list()` \| `nil` | no |  |  | `sanitize(each=[trim, upcase]) validate(list, not_empty, each=[string, regex=\A[A-Z]{2}\z])` |
| `:shipping_rates` | `[String.t() \| MishkaPay.ShippingRate.t()]` \| `nil` | no |  |  | `validate(list)` |
| `:shipping_address` | [`MishkaPay.Address.t()`](`t:MishkaPay.Address.t/0`) \| `nil` | no |  |  |  |
| `:amount_shipping` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:shipping_rate_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:payment_link_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:application_fee` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Refund, :amount}` |
| `:application_fee_percent` | `Decimal.t()` \| `nil` | no |  |  | validator `{MishkaPay.Checkout, :fee_percent}` |
| `:destination` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:on_behalf_of` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:payment_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:setup_intent_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:payment_method_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:subscription_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:amount_total` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:amount_tax` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:amount_discount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |

# `billing`

```elixir
@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`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

# `pages`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
