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

A payment the site's own page takes with the provider's card form (Stripe Elements), without a
checkout page: made on the server with `MishkaPay.create_payment_intent/1`, its
`:client_secret` handed to that buyer's browser, where the provider's script shows the form and
confirms it. Read with `MishkaPay.fetch_payment_intent/3`, changed before it is paid with
`MishkaPay.update_payment_intent/1`, confirmed on the server with
`MishkaPay.confirm_payment_intent/4` (a saved payment method), and ended with
`MishkaPay.cancel_payment_intent/3`. A guarded_struct.

Once paid it is a payment like any other: `MishkaPay.fetch_payment/3` reads it by the same
`:id`, refunds take it, and its webhooks sync the Ash payment row.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys.
  * `:amount` (required to make one): a `Money`, or `%{amount: "19.99", currency: "USD"}`.
  * `:customer_id`: the provider customer who pays (`MishkaPay.create_customer/1`).
  * `:payment_method_id`: a payment method the customer saved, to charge it without the form.
  * `:capture`: `:automatic` (the default) takes the money when it is confirmed, the
    provider's recommended way (Stripe's `automatic_async`); `:automatic_sync` the older way
    (Stripe's `automatic`); `:manual` holds
    it, read as `:requires_capture`, until `MishkaPay.capture_payment/4` takes it or
    `MishkaPay.cancel_payment_intent/3` lets it go.
  * `:setup_future_usage`: `:off_session` keeps the payment method on the customer for later
    charges without the buyer, `:on_session` for later payments the buyer makes.
  * `:automatic_payment_methods`: `true` (the default) offers the payment methods turned on in
    the provider's dashboard; `false` offers cards only.
  * `:description`, `:metadata`: kept with it.
  * `:reference`: the caller's own id for the sale; it makes the idempotency key, so the same
    reference never makes two, and it comes back on the payment. `:owner`: who it is for in the
    caller's app, as on a checkout.

What the provider fills in:

  * `:id` (`pi_...` at Stripe), `:client_secret`: what the provider's script in the buyer's
    browser takes. Send it only to that buyer's page.
  * `:status`: `:requires_payment_method` (waits for the form), `:requires_confirmation`,
    `:requires_action` (the buyer must pass a check, such as 3D Secure), `:processing`,
    `:requires_capture` (held), `:succeeded` or `:canceled`.
  * `:amount_received`, `:failure_code` and `:failure_message` (why the last try failed),
    `:created_at`.

A change (`:id` given) names only what it changes.

# `t`

```elixir
@type t() :: %MishkaPay.PaymentIntent{
  amount: Money.t() | nil,
  amount_received: Money.t() | nil,
  automatic_payment_methods: boolean() | nil,
  capture: (:automatic | :automatic_sync | :manual) | nil,
  client_secret: String.t() | nil,
  created_at: DateTime.t() | nil,
  customer_id: String.t() | nil,
  description: String.t() | nil,
  failure_code: String.t() | nil,
  failure_message: String.t() | nil,
  id: String.t() | nil,
  metadata: map() | nil,
  owner: String.t() | nil,
  payment_method_id: String.t() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  setup_future_usage: (:on_session | :off_session) | nil,
  status: atom() | nil,
  tenant: term() | 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 |  |  |  |
| `:id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:payment_method_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:capture` | `:automatic` \| `:automatic_sync` \| `:manual` \| `nil` | no |  |  | `validate(enum=Atom[automatic::automatic_sync::manual])`<br>validator `{MishkaPay.Checkout, :capture}` |
| `:setup_future_usage` | `:on_session` \| `:off_session` \| `nil` | no |  |  | `validate(enum=Atom[on_session::off_session])`<br>validator `{MishkaPay.PaymentIntent, :usage}` |
| `:automatic_payment_methods` | `boolean()` \| `nil` | no |  |  | `validate(boolean)` |
| `:description` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, max_len=1000)` |
| `: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)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:client_secret` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:status` | `atom()` \| `nil` | no |  |  | `validate(enum=Atom[requires_payment_method::requires_confirmation::requires_action::processing::requires_capture::succeeded::canceled])` |
| `:amount_received` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:failure_code` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:failure_message` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

# `statuses`

```elixir
@spec statuses() :: [atom()]
```

The statuses a payment intent can have.

---

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