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

One payment as the provider sees it, read with `MishkaPay.fetch_payment/3`. A guarded_struct the
provider fills in; the provider is the source of truth, so read it again rather than keep it.

  * `:id`: the provider's id (`pi_...` at Stripe).
  * `:amount`: what was asked, a `Money`; `:amount_refunded`: what went back so far.
  * `:amount_captured`: what the provider took, once paid; less than `:amount` when a held
    payment was captured in part (`MishkaPay.capture_payment/4`).
  * `:status`: `:pending` (not paid yet), `:requires_action` (the buyer must do something, such
    as 3-D Secure), `:authorized` (the money is held on the card and waits for
    `MishkaPay.capture_payment/4` or `MishkaPay.cancel_payment/3`), `:paid`,
    `:partially_refunded`, `:refunded`, `:failed` or `:canceled`.
  * `:reference`: the caller's own id given at checkout; `:owner`: who the sale is for, as the
    checkout named them (`MishkaPay.Checkout`).
  * `:customer_id`, `:customer_email`, `:customer_name`: the buyer, as far as the provider knows
    them.
  * `:description`: the provider's description of the payment; `:metadata`: the extra pairs
    kept with it (Mishka Pay's own reference left out).
  * `:payment_method`: how it was paid, such as `"card"`; for a card, `:card_brand` (`"visa"`)
    and `:card_last4`.
  * `:receipt_url`: the provider's receipt page for the buyer, once paid.
  * `:failure_code`, `:failure_message`: why the last try failed, such as `"insufficient_funds"`.
  * `:disputed`: the buyer's bank has asked for it back (`MishkaPay.Dispute`).
  * `:refunds`: every `MishkaPay.Refund` made on it, newest first.
  * `:checkout_id`, `:items`: the checkout that took it and what it sold, each a
    `MishkaPay.Price` with its provider `:id`, `:product_id`, `:name`, unit `:amount` and
    `:quantity`; what a shop delivers. Read by `MishkaPay.fetch_payment/3`; a payment made
    outside a checkout (a subscription's renewal, a bill) has none, and `list_payments/3` leaves
    them out.
  * `:created_at`: when the provider made it, a `DateTime`.

# `t`

```elixir
@type t() :: %MishkaPay.Payment{
  amount: Money.t(),
  amount_captured: Money.t() | nil,
  amount_refunded: Money.t() | nil,
  card_brand: String.t() | nil,
  card_last4: String.t() | nil,
  checkout_id: String.t() | nil,
  created_at: DateTime.t() | nil,
  customer_email: String.t() | nil,
  customer_id: String.t() | nil,
  customer_name: String.t() | nil,
  description: String.t() | nil,
  disputed: boolean() | nil,
  failure_code: String.t() | nil,
  failure_message: String.t() | nil,
  fraud_review: MishkaPay.Payment.FraudReview.t() | nil,
  fraud_warning: MishkaPay.Payment.FraudWarning.t() | nil,
  id: String.t(),
  items: [MishkaPay.Price.t()] | nil,
  metadata: map() | nil,
  owner: String.t() | nil,
  payment_method: String.t() | nil,
  provider: String.t(),
  receipt_url: String.t() | nil,
  reference: String.t() | nil,
  refunds: [MishkaPay.Refund.t()] | nil,
  status: atom()
}
```

The struct that `builder/1` returns.

| Field | Type | Required | Default | Description | Derives |
| --- | --- | --- | --- | --- | --- |
| `:provider` | `String.t()` | yes |  |  | `validate(not_nil_value, string)` |
| `:id` | `String.t()` | yes |  |  | `validate(not_nil_value, string, not_empty)` |
| `:amount` | `Money.t()` | yes |  |  | validator `{MishkaPay.Money, :field}` |
| `:amount_refunded` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:amount_captured` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:status` | `atom()` | yes |  |  | `validate(not_nil_value, enum=Atom[pending::requires_action::authorized::paid::partially_refunded::refunded::failed::canceled])` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:owner` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:customer_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:customer_email` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:customer_name` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:description` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)` |
| `:payment_method` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:card_brand` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:card_last4` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:receipt_url` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:failure_code` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:failure_message` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:disputed` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:refunds` | [`[MishkaPay.Refund.t()]`](`t:MishkaPay.Refund.t/0`) \| `nil` | no | `[]` |  |  |
| `:checkout_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:items` | [`[MishkaPay.Price.t()]`](`t:MishkaPay.Price.t/0`) \| `nil` | no | `[]` |  |  |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:fraud_review` | [`MishkaPay.Payment.FraudReview.t()`](`t:MishkaPay.Payment.FraudReview.t/0`) \| `nil` | no |  | A payment the provider's fraud rules held for the seller to look at before it goes on (a review, `prv_...` at Stripe Radar). A guarded_struct the provider fills in, read with `MishkaPay.fetch_fraud_review/3` and `MishkaPay.list_fraud_reviews/3`, and let through with `MishkaPay.approve_fraud_review/3`. Refunding the payment closes it the other way. |  |
| `:fraud_warning` | [`MishkaPay.Payment.FraudWarning.t()`](`t:MishkaPay.Payment.FraudWarning.t/0`) \| `nil` | no |  | A card issuer's early warning that a payment looks like fraud (an early fraud warning, `issfr_...` at Stripe Radar), often days before the buyer's bank opens a dispute. A guarded_struct the provider fills in, read with `MishkaPay.fetch_fraud_warning/3` and `MishkaPay.list_fraud_warnings/3`. |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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