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

A seller's own account under a platform (a connected account, `acct_...` at Stripe Connect):
each site of a multi-site platform, or each seller of a marketplace, takes its money there.
Made with `MishkaPay.create_connected_account/1`, read with `MishkaPay.fetch_connected_account/4`
and `MishkaPay.list_connected_accounts/3`, changed with `MishkaPay.update_connected_account/1`
and closed with `MishkaPay.close_connected_account/4`. The seller fills in their details on the
provider's own pages (`MishkaPay.account_link/1`). A guarded_struct.

Once made, the site's keys name it as their `:account_id` (`MishkaPay.Credentials`), so the
site's payments run on it.

What the caller gives:

  * `:provider`, `:tenant`: which provider, with whose keys (the platform's).
  * `:api`: which of the provider's APIs to use, `:v2` or `:v1` (Stripe's Accounts v2 or v1);
    left out, the tenant's `:connect_api` setting (`:v2` by default). A read answers the API it
    was read with.
  * `:configurations`: what the account does, `:merchant` (takes payments from buyers),
    `:recipient` (takes transfers from the platform) and `:customer` (pays the platform);
    `[:merchant, :recipient]` when an account is made without them. Each asks for what it needs: a merchant card
    payments, a recipient transfers into its balance. Accounts v1 has no `:customer`.
  * `:dashboard`: what the seller sees at the provider: `:express` (when an account is made
    without one: a light dashboard), `:full` (the seller's own full account) or `:none` (nothing; the platform
    collects every detail).
  * `:fees_collector`, `:losses_collector`: who pays the provider's fees and who answers for
    losses, `:application` (the platform) or `:stripe` (the provider, with the seller); left
    out, what the dashboard needs (`:application` for `:express` and `:none`, `:stripe` for
    `:full`).
  * `:country`: the seller's country, two letters (`"US"`, `"DE"`).
  * `:email`, `:business_name`: who the seller is, prefilled on their pages.
  * `:capabilities`: more than the configurations ask for, by the provider's names. At Stripe
    on v2 each is its configuration and its path there (`"merchant.klarna_payments"`,
    `"recipient.stripe_balance.stripe_transfers"`); on v1 its plain name (`"transfers"`).
  * `:reference`: the host's own id for the seller; it makes the idempotency key, so the same
    reference never makes two accounts, and it comes back on every read.
  * `:metadata`: string keys and values kept with it.

An update sends only what is given: the configurations and capabilities given are added to
those the account has.

What the provider fills in: `:id`; `:charges_enabled`, `:payouts_enabled` and
`:transfers_enabled` once the seller is set up; `:details_submitted`, whether the seller has
given everything asked of them; `:requirements_due`, what the provider still needs from the
seller; `:disabled_reason`, why a capability is held back; `:capability_status`, each
capability's state (`:active`, `:pending`, `:restricted`, `:rejected`, `:unsupported`,
`:inactive`); `:default_currency`; `:closed`; `:created_at`.

A list at Stripe on v2 answers each account's own fields only (configurations, dashboard,
email, name, metadata, closed): read one with `MishkaPay.fetch_connected_account/4` for its
states and what it still needs.

# `t`

```elixir
@type t() :: %MishkaPay.ConnectedAccount{
  api: (:v2 | :v1) | nil,
  business_name: String.t() | nil,
  capabilities: [String.t()] | nil,
  capability_status: map() | nil,
  charges_enabled: boolean() | nil,
  closed: boolean() | nil,
  configurations: [:merchant | :recipient | :customer] | nil,
  country: String.t() | nil,
  created_at: DateTime.t() | nil,
  dashboard: (:express | :full | :none) | nil,
  default_currency: String.t() | nil,
  details_submitted: boolean() | nil,
  disabled_reason: String.t() | nil,
  email: String.t() | nil,
  fees_collector: (:application | :stripe) | nil,
  id: String.t() | nil,
  link: MishkaPay.ConnectedAccount.Link.t() | nil,
  losses_collector: (:application | :stripe) | nil,
  metadata: map() | nil,
  payouts_enabled: boolean() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  requirements_due: [String.t()] | nil,
  tenant: term() | nil,
  transfers_enabled: boolean() | 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)` |
| `:api` | `:v2` \| `:v1` \| `nil` | no |  |  | `validate(enum=Atom[v2::v1])`<br>validator `{MishkaPay.ConnectedAccount, :api}` |
| `:configurations` | `[:merchant \| :recipient \| :customer]` \| `nil` | no |  |  | `validate(list)`<br>validator `{MishkaPay.ConnectedAccount, :configurations}` |
| `:dashboard` | `:express` \| `:full` \| `:none` \| `nil` | no |  |  | `validate(enum=Atom[express::full::none])`<br>validator `{MishkaPay.ConnectedAccount, :dashboard}` |
| `:fees_collector` | `:application` \| `:stripe` \| `nil` | no |  |  | `validate(enum=Atom[application::stripe])`<br>validator `{MishkaPay.ConnectedAccount, :collector}` |
| `:losses_collector` | `:application` \| `:stripe` \| `nil` | no |  |  | `validate(enum=Atom[application::stripe])`<br>validator `{MishkaPay.ConnectedAccount, :collector}` |
| `:country` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, upcase) validate(string, regex=^[A-Z]{2}$)` |
| `:email` | `String.t()` \| `nil` | no |  |  | `sanitize(trim, downcase) validate(string, email_r)` |
| `:business_name` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=255)` |
| `:capabilities` | `[String.t()]` \| `nil` | no |  |  | `validate(list, each=[string, regex=\A[a-z0-9_]+(\.[a-z0-9_]+)*\z])` |
| `:reference` | `String.t()` \| `nil` | no |  |  | `sanitize(trim) validate(string, not_empty, max_len=200)` |
| `:metadata` | `map()` \| `nil` | no | `%{}` |  | `validate(map)`<br>validator `{MishkaPay.Checkout, :metadata}` |
| `:charges_enabled` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:payouts_enabled` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:transfers_enabled` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:details_submitted` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:requirements_due` | `[String.t()]` \| `nil` | no | `[]` |  | `validate(list)` |
| `:disabled_reason` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:capability_status` | `map()` \| `nil` | no | `%{}` |  | `validate(map)` |
| `:default_currency` | `String.t()` \| `nil` | no |  |  | `validate(string)` |
| `:closed` | `boolean()` \| `nil` | no | `false` |  | `validate(boolean)` |
| `:created_at` | `DateTime.t()` \| `nil` | no |  |  | `validate(struct)` |
| `:link` | [`MishkaPay.ConnectedAccount.Link.t()`](`t:MishkaPay.ConnectedAccount.Link.t/0`) \| `nil` | no |  | A one-time link that sends a seller to the provider's own pages for their connected account (`MishkaPay.ConnectedAccount`). A guarded_struct. |  |

# `builder`

# `enforce_keys`

# `enforce_keys`

# `example`

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

# `keys`

# `keys`

---

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