# `MishkaPay.ConnectedAccount.Link`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/nofile#L1)

A one-time link that sends a seller to the provider's own pages for their connected account
(`MishkaPay.ConnectedAccount`). A guarded_struct.

`MishkaPay.account_link/1` makes one from what the caller gives:

  * `:provider`, `:tenant`, `:account_id`: whose account, with the platform's keys.
  * `:api`: which of the provider's APIs makes the link, `:v2` or `:v1` (Stripe's
    `/v2/core/account_links` or `/v1/account_links`); left out, the tenant's `:connect_api`
    setting (`:v2` by default). Either API links an account made with either.
  * `:type`: `:onboarding` (the default: the seller fills in what the provider needs before
    they take money) or `:update` (they change their details later; only where the platform
    collects them, such as a `:custom` account).
  * `:refresh_url`: where the seller lands when the link ran out or was used already; that page
    makes a new link and sends them on.
  * `:return_url`: where they come back when they are done or leave. Coming back does not mean
    the account is ready: read it again (`:details_submitted`, `:charges_enabled`,
    `:requirements_due`).

Both URLs are `https`, or `http` on `localhost`.

`MishkaPay.login_link/3` makes the other kind, `type: :login`: a link into the seller's own
light dashboard at the provider (Stripe's Express dashboard), only for an `:express` account
that finished onboarding. Stripe makes it only on `/v1/accounts/:id/login_links` (Accounts v2
has none), which takes an account made with either API.

What the provider fills in: `:url`, and `:expires_at` for an onboarding or update link (minutes
at Stripe). Make one per click and never store it.

# `t`

```elixir
@type t() :: %MishkaPay.ConnectedAccount.Link{
  account_id: String.t(),
  api: (:v2 | :v1) | nil,
  created_at: DateTime.t() | nil,
  expires_at: DateTime.t() | nil,
  provider: String.t(),
  refresh_url: String.t() | nil,
  return_url: String.t() | nil,
  tenant: term() | nil,
  type: (:onboarding | :update | :login) | nil,
  url: 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 |  |  |  |
| `:account_id` | `String.t()` | yes |  |  | `sanitize(trim) validate(not_nil_value, string, not_empty)` |
| `:api` | `:v2` \| `:v1` \| `nil` | no |  |  | `validate(enum=Atom[v2::v1])`<br>validator `{MishkaPay.ConnectedAccount, :api}` |
| `:type` | `:onboarding` \| `:update` \| `:login` \| `nil` | no | `:onboarding` |  | `validate(not_nil_value, enum=Atom[onboarding::update::login])`<br>validator `{MishkaPay.ConnectedAccount, :type}` |
| `:refresh_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)`<br>validator `{MishkaPay.Checkout, :return_url}` |
| `:return_url` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty)`<br>validator `{MishkaPay.Checkout, :return_url}` |
| `:url` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:expires_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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