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

Money given back on a payment, in full or in part, made with `MishkaPay.refund/1`. A
guarded_struct.

How often a payment may be refunded is the tenant's choice, read at runtime from its
`MishkaPay.Credentials` (`:refunds`):

  * `:once` (the default): one refund, whole or in part. Another one on that payment is refused,
    and a buyer who wants it again makes a new purchase. The idempotency key comes from the
    payment, so a refund sent again after a lost answer is the same refund.
  * `:many`: part refunds until the payment is used up. Each refund needs its own `:reference`,
    which makes its idempotency key, so the same reference never refunds twice.

What the caller gives:

  * `:provider`, `:tenant`: as for a checkout.
  * `:payment_id`: the payment to refund.
  * `:amount`: how much, a `Money`; left out, the whole payment.
  * `:reason`: `:requested_by_customer`, `:duplicate` or `:fraudulent`.
  * `:reference`: the caller's own id for this refund; needed when the tenant allows many.

What the provider fills in: `:id`, `:status` (`:pending`, `:succeeded`, `:failed`, `:canceled`,
`:requires_action`) and `:created_at`, and `:amount` when it was left out.

# `t`

```elixir
@type t() :: %MishkaPay.Refund{
  amount: Money.t() | nil,
  created_at: DateTime.t() | nil,
  id: String.t() | nil,
  payment_id: String.t(),
  provider: String.t(),
  reason: atom() | nil,
  reference: String.t() | 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 |  |  |  |
| `:payment_id` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Refund, :amount}` |
| `:reason` | `atom()` \| `nil` | no |  |  | `validate(enum=Atom[requested_by_customer::duplicate::fraudulent])` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:status` | `atom()` \| `nil` | no |  |  | `validate(enum=Atom[pending::succeeded::failed::canceled::requires_action])` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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