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

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:`.

# `t`

```elixir
@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()]`](`t:MishkaPay.Price.t/0`) \| `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)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

# `url`

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

---

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