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

Money the platform sends from its own balance to a seller's connected account (a transfer,
`tr_...` at Stripe): the seller's share of a sale the platform took, or any payment to them.
Made with `MishkaPay.create_transfer/1`, read with `MishkaPay.fetch_transfer/3` and
`MishkaPay.list_transfers/3`, and taken back, all or part, with `MishkaPay.reverse_transfer/4`.
A guarded_struct.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with the platform's keys.
  * `:amount`: how much, as money (`%{amount: "12.00", currency: "USD"}`), above zero, in a
    currency the platform's balance holds.
  * `:destination`: the connected account it goes to (`acct_...`).
  * `:reference`: the host's own id for it, required: it makes the idempotency key, so the
    same reference never sends the money twice, and it comes back on every read.
  * `:source_charge_id`: the sale it pays out of (a charge, `ch_...`): the transfer then waits
    for that money to be available instead of the platform's balance.
  * `:transfer_group`: a name tying the payments and transfers of one order together.
  * `:description`, `:metadata`.

What the provider fills in: `:id`, `:amount_reversed` (what was taken back so far),
`:reversed` (`true` once all of it was), `:destination_payment_id` (the payment it made on the
connected account) and `:created_at`.

# `t`

```elixir
@type t() :: %MishkaPay.Transfer{
  amount: Money.t() | nil,
  amount_reversed: Money.t() | nil,
  created_at: DateTime.t() | nil,
  description: String.t() | nil,
  destination: String.t() | nil,
  destination_payment_id: String.t() | nil,
  id: String.t() | nil,
  metadata: map() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  reversed: boolean() | nil,
  source_charge_id: String.t() | nil,
  tenant: term() | nil,
  transfer_group: 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 |  |  |  |
| `:id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:amount` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Refund, :amount}` |
| `:destination` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:source_charge_id` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)` |
| `:transfer_group` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:description` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=500)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:amount_reversed` | `Money.t()` \| `nil` | no |  |  | validator `{MishkaPay.Money, :field}` |
| `:reversed` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:destination_payment_id` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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