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

The calls a project makes to take money: open a checkout, read a payment, refund one; for a
subscription (started by a checkout in `mode: :subscription`) read it, cancel it, take a cancel
back and list its invoices; keep customers (create, read, update, list, delete) and open their billing
portal; save a customer's card with a checkout in `mode: :setup` and keep their saved payment
methods; keep coupons and promotion codes; keep a catalog of products and prices; make payment
links that sell them; end an open
checkout; list payments, subscriptions, invoices, customers, coupons, codes, products and prices
page by page (`MishkaPay.Page`).

    {:ok, checkout} =
      MishkaPay.checkout(%{
        provider: "stripe",
        tenant: site_id,
        items: [%{name: "Ebook", amount: %{amount: "19.99", currency: "USD"}}],
        success_url: "https://shop.test/thanks",
        cancel_url: "https://shop.test/cart",
        reference: order.id
      })

    redirect(conn, external: checkout.url)

Each call names a provider by its id, finds it among the installed providers
(`MishkaPay.Provider.fetch/1`), checks it has the capability, takes the tenant's keys from
`MishkaPay.Credentials` and hands the provider a checked guarded_struct. The answer is a
guarded_struct or a `MishkaPay.Errors` error, the same for every provider. This module never
names a provider: a project chooses which run by supervising their plugins.

## Before a checkout

`checkout/1` fires `mishka_pay:checkout:before` (`MishkaPay.Events.checkout_before/0`) with the
checked checkout. A host plugin may change it (add metadata, set the customer) or refuse it with
a reason, which comes back as a `MishkaPay.Errors.Refused` error. A gate that does not answer
refuses too, with the reason why: it cannot run, raises, exits or throws, gives no answer within
`config :mishka_pay, checkout_gate_timeout: ms` (5 seconds), or answers something that is not
a checkout (`:invalid_answer`). A sale never goes ahead on a gate that did not say yes. The gate
runs like the keys plugins, in a task that cannot take the caller down.

## Telemetry

Each call is a span, `[:mishka_pay, operation, :start | :stop]`, with `:provider` and `:tenant`
in its metadata and, on `:stop`, the `:outcome`: `:ok` or the error's class (`:invalid`,
`:provider`, `:unknown`). Never a key or a buyer's details. The operations:

  * checkouts and payments: `:checkout`, `:checkout_read`, `:checkout_expire`, `:payment`,
    `:payment_list`, `:payment_capture`, `:payment_cancel`, `:refund`, `:refund_read`,
    `:refund_list`;
  * the site's own card form: `:payment_intent_create`, `:payment_intent`,
    `:payment_intent_update`, `:payment_intent_confirm`, `:payment_intent_cancel`,
    `:setup_intent_create`, `:setup_intent`, `:setup_intent_confirm`, `:setup_intent_cancel`;
  * subscriptions: `:subscription`, `:subscription_cancel`, `:subscription_resume`,
    `:subscription_change`, `:subscription_preview`, `:subscription_pause`,
    `:subscription_unpause`, `:subscription_list`, `:subscription_search`, `:invoices`,
    `:invoice`, `:invoice_upcoming`, and their schedules: `:subscription_schedule_create`,
    `:subscription_schedule`, `:subscription_schedule_list`, `:subscription_schedule_update`,
    `:subscription_schedule_release`, `:subscription_schedule_cancel`;
  * one-off bills: `:invoice_create`, `:invoice_finalize`, `:invoice_send`, `:invoice_pay`,
    `:invoice_void`, `:invoice_uncollectible`, `:invoice_delete`, and charges kept for a bill:
    `:invoice_item_create`, `:invoice_item_update`, `:invoice_item_delete`,
    `:invoice_item_list`, and credit notes: `:credit_note_create`, `:credit_note_preview`,
    `:credit_note`, `:credit_note_void`, `:credit_note_list`, `:credit_note_line_list`;
  * customers: `:customer_create`, `:customer_update`, `:customer`, `:customer_list`,
    `:customer_search`, `:customer_delete`, `:portal`, the portal's setups:
    `:portal_configuration_create`, `:portal_configuration_update`, `:portal_configuration`,
    `:portal_configuration_list`, and their tax ids: `:tax_id_create`, `:tax_id_list`,
    `:tax_id_delete`;
  * saved payment methods: `:payment_method_list`, `:payment_method`,
    `:payment_method_detach`, `:payment_method_default`;
  * tax outside a checkout: `:tax_calculate`, `:tax_record`; tax rates set by hand:
    `:tax_rate_create`, `:tax_rate`, `:tax_rate_update`, `:tax_rate_list`; the tax setup:
    `:tax_registration_create`, `:tax_registration_list`, `:tax_registration_expire`,
    `:tax_settings`, `:tax_settings_update`;
  * shipping: `:shipping_rate_create`, `:shipping_rate_list`;
  * discounts: `:coupon_create`, `:coupon`, `:coupon_list`, `:coupon_delete`,
    `:promotion_code_create`, `:promotion_code`, `:promotion_code_list`,
    `:promotion_code_update`;
  * the catalog: `:product_create`, `:product`, `:product_update`, `:product_list`,
    `:price_create`, `:price`, `:price_update`, `:price_list`;
  * payment links: `:payment_link_create`, `:payment_link`, `:payment_link_update`,
    `:payment_link_list`;
  * disputes: `:dispute`, `:dispute_list`, `:dispute_update`, `:dispute_accept`;
  * fraud: `:fraud_warning`, `:fraud_warning_list`, `:fraud_review`, `:fraud_review_list`,
    `:fraud_review_approve`;
  * files: `:file_upload`, `:file`, `:file_link`;
  * usage billing: `:meter_create`, `:meter`, `:meter_update`, `:meter_list`,
    `:meter_deactivate`, `:meter_reactivate`, `:usage_report`, `:usage_cancel`,
    `:usage_summary`;
  * entitlements: `:feature_create`, `:feature_attach`, `:entitlement_list`;
  * money views: `:balance`, `:balance_transaction_list`, `:customer_balance_adjust`,
    `:customer_balance_list`;
  * a platform's sellers: `:connected_account_create`, `:connected_account`,
    `:connected_account_update`, `:connected_account_list`, `:connected_account_close`,
    `:account_link`, `:login_link`, `:application_fee`, `:application_fee_list`,
    `:application_fee_refund`; money between accounts: `:transfer_create`, `:transfer`,
    `:transfer_list`, `:transfer_reverse`, `:payout`, `:payout_list`, `:payout_cancel`;
  * events: `:event_list`;
  * a call to the provider's own API: `:raw_request`.

# `accept_dispute`

```elixir
@spec accept_dispute(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Dispute.t()} | {:error, Splode.Error.t()}
```

Accepts dispute `dispute_id`: the seller does not contest it, and it closes as lost.

# `account_link`

```elixir
@spec account_link(map()) ::
  {:ok, MishkaPay.ConnectedAccount.Link.t()} | {:error, Splode.Error.t()}
```

Makes a one-time link (`MishkaPay.ConnectedAccount.Link`) that sends a seller to the provider's pages for
their connected account: `:account_id`, `:type` (`:onboarding` or `:update`), `:refresh_url`
and `:return_url`. Redirect the seller to its `:url` at once; it runs out in minutes.

# `adjust_customer_balance`

```elixir
@spec adjust_customer_balance(
  String.t(),
  String.t(),
  Money.t() | map(),
  term(),
  keyword()
) ::
  {:ok, MishkaPay.Customer.BalanceTransaction.t()} | {:error, Splode.Error.t()}
```

Changes customer `customer_id`'s balance by `money` (a `Money`, or a map with `:amount` and
`:currency`): below zero gives credit taken off their next bills, above zero adds a debit.
`description:` says why; `reference:` makes it happen once. Answers the
`MishkaPay.Customer.BalanceTransaction` with the balance after.

# `approve_fraud_review`

```elixir
@spec approve_fraud_review(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Payment.FraudReview.t()} | {:error, Splode.Error.t()}
```

Approves open review `review_id`: the seller trusts the payment and it goes on. Answers the
review, closed. To turn it down instead, refund the payment.

# `archive_price`

```elixir
@spec archive_price(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Price.t()} | {:error, Splode.Error.t()}
```

Takes price `price_id` off sale (`active: false`): a checkout can no longer sell it. A provider
never deletes a price that was used.

# `archive_product`

```elixir
@spec archive_product(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Product.t()} | {:error, Splode.Error.t()}
```

Takes product `product_id` off sale (`active: false`). Past sales keep it; a provider never
deletes a product that sold.

# `attach_feature`

```elixir
@spec attach_feature(String.t(), String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Feature.t()} | {:error, Splode.Error.t()}
```

Attaches feature `feature_id` to catalog product `product_id`: a customer who buys the product
is entitled to the feature. Answers the feature.

# `calculate_tax`

```elixir
@spec calculate_tax(map()) ::
  {:ok, MishkaPay.TaxCalculation.t()} | {:error, Splode.Error.t()}
```

Counts the tax on a sale made outside the provider's checkout, from `attrs` (see
`MishkaPay.TaxCalculation`): its lines, the buyer's address or customer, and shipping. Show the
answer's `:tax_amount_exclusive` and charge its `:amount_total`; once paid, report the sale
with `record_tax/4`.

    MishkaPay.calculate_tax(%{
      provider: "stripe",
      tenant: site_id,
      items: [%{reference: "sku-1", amount: %{amount: "30.00", currency: "EUR"}, quantity: 2}],
      address: %{country: "NL", postal_code: "1012"}
    })

# `cancel_payment`

```elixir
@spec cancel_payment(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Payment.t()} | {:error, Splode.Error.t()}
```

Lets the money held on `:authorized` payment `payment_id` go back to the buyer; the payment ends
`:canceled`.

# `cancel_payment_intent`

```elixir
@spec cancel_payment_intent(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.PaymentIntent.t()} | {:error, Splode.Error.t()}
```

Cancels payment intent `payment_intent_id` before it is paid, or lets the money a held one
(`:requires_capture`) keeps go back. Answers it `:canceled`.

# `cancel_payout`

```elixir
@spec cancel_payout(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Balance.Payout.t()} | {:error, Splode.Error.t()}
```

Stops payout `payout_id` while it is still `:pending`; answers it `:canceled`.

# `cancel_setup_intent`

```elixir
@spec cancel_setup_intent(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.SetupIntent.t()} | {:error, Splode.Error.t()}
```

Cancels setup intent `setup_intent_id`, which has not succeeded. Answers it `:canceled`.

# `cancel_subscription`

```elixir
@spec cancel_subscription(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

Cancels subscription `subscription_id`. With `at: :period_end` (the default) the buyer keeps
what they paid for until the period ends, and `resume_subscription/3` can still take it back;
with `at: :now` it ends at once.

# `cancel_subscription_schedule`

```elixir
@spec cancel_subscription_schedule(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Subscription.Schedule.t()} | {:error, Splode.Error.t()}
```

Cancels subscription schedule `schedule_id` and ends its subscription now. `invoice_now: true`
bills what is not billed yet, `prorate: true` credits the time not used; each left out is the
provider's default.

# `cancel_usage`

```elixir
@spec cancel_usage(map()) ::
  {:ok, MishkaPay.Usage.Cancellation.t()} | {:error, Splode.Error.t()}
```

Takes back a usage report sent by mistake, from `attrs` (see `MishkaPay.Usage.Cancellation`):
the meter's `:event_name` and the report's `:usage_id` (the `:id` `report_usage/1` answered).
The same cancel sent again is one cancel. A provider takes a report back only for a while
(Stripe: 24 hours); after that, report the value again below zero.

    {:ok, usage} = MishkaPay.report_usage(%{..., reference: "req-42"})
    MishkaPay.cancel_usage(%{provider: "stripe", tenant: site_id, event_name: "api_call",
                             usage_id: usage.id})

# `capture_payment`

```elixir
@spec capture_payment(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Payment.t()} | {:error, Splode.Error.t()}
```

Takes the money held on `:authorized` payment `payment_id` (a checkout with `capture: :manual`):
all of it, or `amount:` (a `Money`, or a map of `:amount` and `:currency`, in the payment's
currency) and the rest is let go. Answers the payment, `:paid`, with `:amount_captured`.

# `change_subscription`

```elixir
@spec change_subscription(map()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

Changes a running subscription (see `MishkaPay.Subscription.Change`): a new plan
(`:price_id`), a new quantity, or both, billed the way `:proration` says. Answers the
subscription after. Preview it first with `preview_subscription_change/1`.

# `checkout`

```elixir
@spec checkout(map()) :: {:ok, MishkaPay.Checkout.t()} | {:error, Splode.Error.t()}
```

Opens a checkout from `attrs` (see `MishkaPay.Checkout`) and answers it with the provider's page.

# `close_connected_account`

```elixir
@spec close_connected_account(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.ConnectedAccount.t()} | {:error, Splode.Error.t()}
```

Closes connected account `account_id` for good: it takes no more payments or payouts, and is
still read with `closed: true`. `api:` as in `fetch_connected_account/4`. At Stripe on v2 the
account is read first, since Stripe closes it only with every configuration it has; on v1 it
is turned down (rejected) with `reason:` (`"fraud_other"`, `"terms_of_service"`, `"credit"`,
`"other"`...; `"other"` when left out). Answers the account after.

# `confirm_payment_intent`

```elixir
@spec confirm_payment_intent(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.PaymentIntent.t()} | {:error, Splode.Error.t()}
```

Confirms payment intent `payment_intent_id` on the server: `payment_method_id:` a saved payment
method, and `return_url:` where a payment method's own page (3D Secure, a bank) sends the
buyer back (`https`, or `http` on `localhost`). A page with the card form confirms in the
browser instead.

# `confirm_setup_intent`

```elixir
@spec confirm_setup_intent(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.SetupIntent.t()} | {:error, Splode.Error.t()}
```

Confirms setup intent `setup_intent_id` on the server, with `payment_method_id:` and
`return_url:` as `confirm_payment_intent/4`.

# `create_connected_account`

```elixir
@spec create_connected_account(map()) ::
  {:ok, MishkaPay.ConnectedAccount.t()} | {:error, Splode.Error.t()}
```

Makes a connected account for a seller from `attrs` (see `MishkaPay.ConnectedAccount`), with
the platform's keys: `:configurations` (`[:merchant, :recipient]` by default), `:dashboard`
(`:express` by default), `:country`, `:email`, `:capabilities`, `:api` (else the tenant's
`:connect_api`, `:v2` by default) and a `:reference` that makes it once. Then send the seller to `account_link/1`, and give the
seller's site its id as `:account_id` in its keys.

# `create_coupon`

```elixir
@spec create_coupon(map()) :: {:ok, MishkaPay.Coupon.t()} | {:error, Splode.Error.t()}
```

Makes a coupon from `attrs` (see `MishkaPay.Coupon`) at `attrs.provider`.

# `create_credit_note`

```elixir
@spec create_credit_note(map()) ::
  {:ok, MishkaPay.CreditNote.t()} | {:error, Splode.Error.t()}
```

Makes a credit note from `attrs` (see `MishkaPay.CreditNote`) on finalized bill
`:invoice_id`: an `:amount` of it or `:lines`, a `:reason`, and on a paid bill where the money
goes (`:refund_amount`, `:credit_amount` onto the customer's balance, `:out_of_band_amount`).
Its `:reference` makes it once. Try it first with `preview_credit_note/1`.

    MishkaPay.create_credit_note(%{provider: "stripe", tenant: site_id, invoice_id: bill.id,
                                   amount: %{amount: "20", currency: "USD"},
                                   refund_amount: %{amount: "20", currency: "USD"},
                                   reason: :order_change, reference: "credit-" <> order.id})

# `create_customer`

```elixir
@spec create_customer(map()) ::
  {:ok, MishkaPay.Customer.t()} | {:error, Splode.Error.t()}
```

Makes a customer from `attrs` (see `MishkaPay.Customer`): `:provider`, `:tenant`, and the
buyer's `:email`, `:name`, `:phone`, `:address`, `:reference`, `:metadata`; `:api` picks the
provider's API (else the tenant's `:customer_api`, `:v2` by default: at Stripe an account with
the customer configuration, `acct_...`). Keep its `:id` on the host's user to sell to them
again.

# `create_feature`

```elixir
@spec create_feature(map()) ::
  {:ok, MishkaPay.Feature.t()} | {:error, Splode.Error.t()}
```

Makes a feature from `attrs` (see `MishkaPay.Feature`): a `:name` and the `:lookup_key` the
host checks access by.

# `create_invoice`

```elixir
@spec create_invoice(map()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

Makes a draft bill for a customer from `attrs` (see `MishkaPay.Invoice.Draft`), with its items,
and answers it as a `MishkaPay.Invoice`. Open it with `finalize_invoice/3`.

# `create_invoice_item`

```elixir
@spec create_invoice_item(map()) ::
  {:ok, MishkaPay.Invoice.Item.t()} | {:error, Splode.Error.t()}
```

Adds a charge for a customer from `attrs` (see `MishkaPay.Invoice.Item`): a catalog
`:price_id`, or a `:name` and `:amount`, with a `:quantity`. Without `:invoice_id` it waits and
goes on the customer's next bill (a renewal or a one-off bill); with it, on that draft bill.

    MishkaPay.create_invoice_item(%{provider: "stripe", tenant: site_id, customer_id: id,
                                    name: "Setup fee", amount: %{amount: "49", currency: "USD"},
                                    reference: "setup-" <> account.id})

# `create_meter`

```elixir
@spec create_meter(map()) :: {:ok, MishkaPay.Meter.t()} | {:error, Splode.Error.t()}
```

Makes a meter from `attrs` (see `MishkaPay.Meter`): its `:event_name`, a `:name`, and its
`:aggregation` (`:sum`, `:count` or `:last`). A price with its `:meter_id` and an `:interval`
bills what it counts.

# `create_payment_intent`

```elixir
@spec create_payment_intent(map()) ::
  {:ok, MishkaPay.PaymentIntent.t()} | {:error, Splode.Error.t()}
```

Makes a payment intent from `attrs` (see `MishkaPay.PaymentIntent`): an `:amount`, and the
`:customer_id`, `:payment_method_id`, `:capture`, `:setup_future_usage` and `:reference` it
needs. Hand its `:client_secret` to that buyer's page only, where the provider's card form
(Stripe Elements) confirms it; then read it again before giving access.

# `create_payment_link`

```elixir
@spec create_payment_link(map()) ::
  {:ok, MishkaPay.PaymentLink.t()} | {:error, Splode.Error.t()}
```

Makes a payment link from `attrs` (see `MishkaPay.PaymentLink`): catalog prices by id, sold to
anyone who opens its `:url`.

# `create_portal_configuration`

```elixir
@spec create_portal_configuration(map()) ::
  {:ok, MishkaPay.PortalSession.Configuration.t()} | {:error, Splode.Error.t()}
```

Makes a setup of the customer portal from `attrs` (see `MishkaPay.PortalSession.Configuration`): what
buyers may do there (cancel, switch plan and to which prices, change their card or details, see
their bills) and the page's header. A portal session uses it by its `:id` (`:configuration`).

    MishkaPay.create_portal_configuration(%{provider: "stripe", tenant: site_id,
      name: "Teams", subscription_cancel: :at_period_end, invoice_history: true,
      payment_method_update: true, subscription_update: [:price, :quantity],
      plans: [%{product_id: "prod_team", price_ids: ["price_monthly", "price_yearly"]}]})

# `create_price`

```elixir
@spec create_price(map()) :: {:ok, MishkaPay.Price.t()} | {:error, Splode.Error.t()}
```

Makes a price of product `attrs.product_id` from `attrs` (see `MishkaPay.Price`): an `:amount`,
and an `:interval` for a plan.

# `create_product`

```elixir
@spec create_product(map()) ::
  {:ok, MishkaPay.Product.t()} | {:error, Splode.Error.t()}
```

Makes a product from `attrs` (see `MishkaPay.Product`) in `attrs.provider`'s catalog.

# `create_promotion_code`

```elixir
@spec create_promotion_code(map()) ::
  {:ok, MishkaPay.Coupon.PromotionCode.t()} | {:error, Splode.Error.t()}
```

Makes a promotion code from `attrs` (see `MishkaPay.Coupon.PromotionCode`) at `attrs.provider`.

# `create_setup_intent`

```elixir
@spec create_setup_intent(map()) ::
  {:ok, MishkaPay.SetupIntent.t()} | {:error, Splode.Error.t()}
```

Makes a setup intent from `attrs` (see `MishkaPay.SetupIntent`): it saves a payment method on
`:customer_id` with the provider's card form on the site's own page, and charges nothing. Hand
its `:client_secret` to that buyer's page only.

# `create_shipping_rate`

```elixir
@spec create_shipping_rate(map()) ::
  {:ok, MishkaPay.ShippingRate.t()} | {:error, Splode.Error.t()}
```

Makes a shipping rate from `attrs` (see `MishkaPay.ShippingRate`): its `:name`, its `:amount`
for the whole order, and a delivery estimate. A checkout offers it by its `:id` in
`:shipping_rates`.

# `create_subscription_schedule`

```elixir
@spec create_subscription_schedule(map()) ::
  {:ok, MishkaPay.Subscription.Schedule.t()} | {:error, Splode.Error.t()}
```

Makes a subscription schedule from `attrs` (see `MishkaPay.Subscription.Schedule`): from a
running `:subscription_id`, or for a `:customer_id` with its `:phases`. Its `:reference` makes
it once. The provider needs `:subscription_schedule`.

    MishkaPay.create_subscription_schedule(%{provider: "stripe", tenant: site_id,
      customer_id: customer.id, end_behavior: :cancel, reference: "member-" <> member.id,
      phases: [%{items: [%{id: intro.id}], iterations: 3, interval: :month},
               %{items: [%{id: full.id}], iterations: 9, interval: :month}]})

# `create_tax_id`

```elixir
@spec create_tax_id(String.t(), String.t(), map(), term()) ::
  {:ok, MishkaPay.Customer.TaxId.t()} | {:error, Splode.Error.t()}
```

Adds a business buyer's tax id to customer `customer_id` from `attrs` (see `MishkaPay.Customer.TaxId`):
its `:type`, such as `"eu_vat"`, and its `:value`. The provider prints it on the customer's
invoices, and checks it against a government register for the kinds it can
(`:verification`).

    MishkaPay.create_tax_id("stripe", "cus_123", %{type: "eu_vat", value: "DE123456789"}, site_id)

# `create_tax_rate`

```elixir
@spec create_tax_rate(map()) ::
  {:ok, MishkaPay.TaxRate.t()} | {:error, Splode.Error.t()}
```

Makes a tax rate from `attrs` (see `MishkaPay.TaxRate`): a `:display_name`, a `:percentage` and
whether it is `:inclusive`, and where it applies. Put its `:id` in a line's or a bill's
`:tax_rate_ids`. Its `:reference` makes it once.

# `create_tax_registration`

```elixir
@spec create_tax_registration(map()) ::
  {:ok, MishkaPay.TaxSettings.Registration.t()} | {:error, Splode.Error.t()}
```

Registers the seller to collect tax in a country, from `attrs` (see `MishkaPay.TaxSettings.Registration`):
its `:country` and `:type`, a `:state` where the kind needs one, the `:place_of_supply_scheme`
of a standard registration, and when it starts and ends.
The provider's tax counting then charges tax there.

# `create_transfer`

```elixir
@spec create_transfer(map()) ::
  {:ok, MishkaPay.Transfer.t()} | {:error, Splode.Error.t()}
```

Sends money from the platform's balance to a connected account, from `attrs` (see
`MishkaPay.Transfer`): `:amount`, `:destination` and a `:reference` that sends it once.

# `deactivate_meter`

```elixir
@spec deactivate_meter(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Meter.t()} | {:error, Splode.Error.t()}
```

Turns meter `meter_id` off: it takes no more usage, and no new price can bill it. A provider
never deletes a meter.

# `delete_coupon`

```elixir
@spec delete_coupon(String.t(), String.t(), term()) ::
  :ok | {:error, Splode.Error.t()}
```

Removes coupon `coupon_id` at `provider`, so no checkout or code applies it again. What it
already took off stays taken off.

# `delete_customer`

```elixir
@spec delete_customer(String.t(), String.t(), term()) ::
  :ok | {:error, Splode.Error.t()}
```

Deletes customer `customer_id` at `provider` for good, such as for a person's erase request.
The provider drops their saved cards and ends their running subscriptions at once (Stripe
does); past payments and invoices stay. The customer reads back as deleted after
(`MishkaPay.Errors.Rejected` with code `"customer_deleted"`).

# `delete_invoice`

```elixir
@spec delete_invoice(String.t(), String.t(), term()) ::
  :ok | {:error, Splode.Error.t()}
```

Deletes draft bill `invoice_id`; an open one cannot be deleted, only voided.

# `delete_invoice_item`

```elixir
@spec delete_invoice_item(String.t(), String.t(), term()) ::
  :ok | {:error, Splode.Error.t()}
```

Removes invoice item `invoice_item_id`; one on a finalized bill cannot go.

# `delete_tax_id`

```elixir
@spec delete_tax_id(String.t(), String.t(), String.t(), term()) ::
  :ok | {:error, Splode.Error.t()}
```

Removes tax id `tax_id_id` from customer `customer_id`; past invoices keep it.

# `detach_payment_method`

```elixir
@spec detach_payment_method(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Customer.PaymentMethod.t()} | {:error, Splode.Error.t()}
```

Takes saved payment method `payment_method_id` off its customer at `provider`, for good: it
can no longer be charged or saved again. Answers it after, with no `:customer_id`.

# `expire_checkout`

```elixir
@spec expire_checkout(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Checkout.t()} | {:error, Splode.Error.t()}
```

Ends open checkout `checkout_id` at `provider` so it can no longer be paid, and answers it
(`status: :expired`). Call it when a buyer walks away and the stock held for them should be
free again; a checkout already paid or expired is refused.

# `expire_tax_registration`

```elixir
@spec expire_tax_registration(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.TaxSettings.Registration.t()} | {:error, Splode.Error.t()}
```

Ends tax registration `registration_id`, now or `at:` a later `DateTime`: the provider stops
charging tax there. A registration is never deleted. Answers it after.

# `fetch_application_fee`

```elixir
@spec fetch_application_fee(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.ApplicationFee.t()} | {:error, Splode.Error.t()}
```

Reads application fee `fee_id` (`MishkaPay.ApplicationFee`): the platform's cut of a seller's
sale, and what of it was given back.

# `fetch_balance`

```elixir
@spec fetch_balance(String.t(), term()) ::
  {:ok, MishkaPay.Balance.t()} | {:error, Splode.Error.t()}
```

The seller's balance at `provider` (`MishkaPay.Balance`): available and pending, per currency.

# `fetch_checkout`

```elixir
@spec fetch_checkout(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Checkout.t()} | {:error, Splode.Error.t()}
```

Reads checkout `checkout_id` again from `provider`, with `tenant`'s keys: its `:status` and the
`:payment_id` it made. A success page calls it with the id the provider put in its URL, to show
the sale at once without waiting for the webhook.

# `fetch_connected_account`

```elixir
@spec fetch_connected_account(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.ConnectedAccount.t()} | {:error, Splode.Error.t()}
```

Reads connected account `account_id` (`MishkaPay.ConnectedAccount`): whether it can take
payments, payouts and transfers yet, and what the provider still needs from the seller.
`api:` reads it with `:v2` or `:v1` instead of the tenant's `:connect_api` (at Stripe either
reads an account made with either).

# `fetch_coupon`

```elixir
@spec fetch_coupon(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Coupon.t()} | {:error, Splode.Error.t()}
```

Reads coupon `coupon_id` again from `provider`, with `tenant`'s keys.

# `fetch_credit_note`

```elixir
@spec fetch_credit_note(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.CreditNote.t()} | {:error, Splode.Error.t()}
```

Reads credit note `credit_note_id` again from `provider`, with `tenant`'s keys.

# `fetch_customer`

```elixir
@spec fetch_customer(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Customer.t()} | {:error, Splode.Error.t()}
```

Reads customer `customer_id` again from `provider`, with `tenant`'s keys, on the API its id
belongs to (at Stripe `acct_...` on Accounts v2, `cus_...` on Customers).

# `fetch_dispute`

```elixir
@spec fetch_dispute(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Dispute.t()} | {:error, Splode.Error.t()}
```

Reads dispute `dispute_id` from `provider`, with `tenant`'s keys.

# `fetch_file`

```elixir
@spec fetch_file(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.File.t()} | {:error, Splode.Error.t()}
```

Reads file `file_id` from `provider`, with `tenant`'s keys.

# `fetch_fraud_review`

```elixir
@spec fetch_fraud_review(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Payment.FraudReview.t()} | {:error, Splode.Error.t()}
```

Reads review `review_id` (`MishkaPay.Payment.FraudReview`), open or closed.

# `fetch_fraud_warning`

```elixir
@spec fetch_fraud_warning(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Payment.FraudWarning.t()} | {:error, Splode.Error.t()}
```

Reads early fraud warning `warning_id` (`MishkaPay.Payment.FraudWarning`): a card issuer saying a
payment looks like fraud, before any dispute.

# `fetch_invoice`

```elixir
@spec fetch_invoice(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

Reads invoice `invoice_id` from `provider`, with its lines, bill page and PDF.

# `fetch_meter`

```elixir
@spec fetch_meter(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Meter.t()} | {:error, Splode.Error.t()}
```

Reads meter `meter_id` again from `provider`, with `tenant`'s keys.

# `fetch_payment`

```elixir
@spec fetch_payment(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Payment.t()} | {:error, Splode.Error.t()}
```

Reads payment `payment_id` again from `provider`, with `tenant`'s keys.

# `fetch_payment_intent`

```elixir
@spec fetch_payment_intent(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.PaymentIntent.t()} | {:error, Splode.Error.t()}
```

Reads payment intent `payment_intent_id` from `provider`, with its status.

# `fetch_payment_link`

```elixir
@spec fetch_payment_link(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.PaymentLink.t()} | {:error, Splode.Error.t()}
```

Reads payment link `payment_link_id` again from `provider`, with `tenant`'s keys.

# `fetch_payment_method`

```elixir
@spec fetch_payment_method(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Customer.PaymentMethod.t()} | {:error, Splode.Error.t()}
```

Reads saved payment method `payment_method_id` again from `provider`, with its card.

# `fetch_payout`

```elixir
@spec fetch_payout(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Balance.Payout.t()} | {:error, Splode.Error.t()}
```

Reads payout `payout_id` (`MishkaPay.Balance.Payout`) of the account `tenant`'s keys act for: the
platform's own, or the connected account they name.

# `fetch_portal_configuration`

```elixir
@spec fetch_portal_configuration(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.PortalSession.Configuration.t()} | {:error, Splode.Error.t()}
```

Reads portal setup `configuration_id` from `provider`, with `tenant`'s keys.

# `fetch_price`

```elixir
@spec fetch_price(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Price.t()} | {:error, Splode.Error.t()}
```

Reads price `price_id` again from `provider`, with `tenant`'s keys.

# `fetch_product`

```elixir
@spec fetch_product(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Product.t()} | {:error, Splode.Error.t()}
```

Reads product `product_id` again from `provider`, with `tenant`'s keys.

# `fetch_promotion_code`

```elixir
@spec fetch_promotion_code(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Coupon.PromotionCode.t()} | {:error, Splode.Error.t()}
```

Reads promotion code `promotion_code_id` again from `provider`, with `tenant`'s keys.

# `fetch_refund`

```elixir
@spec fetch_refund(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Refund.t()} | {:error, Splode.Error.t()}
```

Reads refund `refund_id` from `provider` again, with its status.

# `fetch_setup_intent`

```elixir
@spec fetch_setup_intent(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.SetupIntent.t()} | {:error, Splode.Error.t()}
```

Reads setup intent `setup_intent_id` from `provider`, with its status.

# `fetch_subscription`

```elixir
@spec fetch_subscription(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

Reads subscription `subscription_id` again from `provider`, with `tenant`'s keys.

# `fetch_subscription_schedule`

```elixir
@spec fetch_subscription_schedule(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Subscription.Schedule.t()} | {:error, Splode.Error.t()}
```

Reads subscription schedule `schedule_id` again from `provider`, with its phases.

# `fetch_tax_rate`

```elixir
@spec fetch_tax_rate(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.TaxRate.t()} | {:error, Splode.Error.t()}
```

Reads tax rate `tax_rate_id` from `provider`, with `tenant`'s keys.

# `fetch_tax_settings`

```elixir
@spec fetch_tax_settings(String.t(), term()) ::
  {:ok, MishkaPay.TaxSettings.t()} | {:error, Splode.Error.t()}
```

Reads `tenant`'s tax settings at `provider` (`MishkaPay.TaxSettings`).

# `fetch_transfer`

```elixir
@spec fetch_transfer(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Transfer.t()} | {:error, Splode.Error.t()}
```

Reads transfer `transfer_id` (`MishkaPay.Transfer`), with what was taken back of it.

# `file_link`

```elixir
@spec file_link(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.File.Link.t()} | {:error, Splode.Error.t()}
```

Makes a public link to file `file_id` (`MishkaPay.File.Link`), an address a site can show to a
person without any key. `expires_at:` (a `DateTime` still to come) ends it; without it, it
never ends.

# `finalize_invoice`

```elixir
@spec finalize_invoice(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

Opens draft bill `invoice_id` for payment: it gets its number, and its customer can pay it.

# `list_application_fees`

```elixir
@spec list_application_fees(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the platform's application fees, newest first (`MishkaPay.Page` of
`MishkaPay.ApplicationFee`): `charge_id:` only one sale's, plus `limit:` and `after:`.

# `list_balance_transactions`

```elixir
@spec list_balance_transactions(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the movements of the seller's balance, newest first (`MishkaPay.Page` of
`MishkaPay.Balance.Transaction`): `payout_id:` those one payout paid out, `type:` only one kind
(the provider's name, such as `"charge"`), plus `limit:` and `after:`.

# `list_connected_accounts`

```elixir
@spec list_connected_accounts(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the platform's connected accounts, newest first (`MishkaPay.Page` of
`MishkaPay.ConnectedAccount`), with `limit:` and `after:`, and `api:` (`:v2` or `:v1`, else
the tenant's `:connect_api`). A Stripe v2 page holds at most 20. On v2 also `configurations:` (only accounts with all of them)
and `closed: true` (only closed ones; left out, only open ones); each account answers its own
fields only, so read one for its states.

# `list_coupons`

```elixir
@spec list_coupons(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of coupons at `provider`, newest first (`MishkaPay.Page`): `limit:`, `after:`.

# `list_credit_note_lines`

```elixir
@spec list_credit_note_lines(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of credit note `credit_note_id`'s lines (`MishkaPay.Page` of
`MishkaPay.CreditNote.Lines`), plus `limit:` and `after:`.

# `list_credit_notes`

```elixir
@spec list_credit_notes(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of credit notes at `provider`, newest first (`MishkaPay.Page` of
`MishkaPay.CreditNote`): `invoice_id:` those on one bill, `customer_id:` one customer's, plus
`limit:` and `after:`.

# `list_customer_balance`

```elixir
@spec list_customer_balance(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the changes to customer `customer_id`'s balance, newest first (`MishkaPay.Page` of
`MishkaPay.Customer.BalanceTransaction`), plus `limit:` and `after:`.

# `list_customers`

```elixir
@spec list_customers(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of customers at `provider`, newest first (`MishkaPay.Page`): `email:` only those with
that email, plus the list options `limit:` and `after:`. `api:` lists on `:v2` or `:v1` instead
of the tenant's `:customer_api`; Stripe's Accounts v2 lists have no email filter (find by email
with `search_customers/3`) and hold at most 20 a page.

# `list_disputes`

```elixir
@spec list_disputes(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of disputes at `provider`, newest first (`MishkaPay.Page`): `payment_id:` only one
payment's, plus `limit:` and `after:`.

# `list_entitlements`

```elixir
@spec list_entitlements(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the features customer `customer_id` may use now (`MishkaPay.Page` of
`MishkaPay.Feature.Entitlement`), plus `limit:` and `after:`. Check access by their `:lookup_key`.

# `list_events`

```elixir
@spec list_events(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of `provider`'s events for `tenant`, newest first (`MishkaPay.Page`), each a
`MishkaPay.Event`: `since:` a `DateTime`, `types:` a list of event types, `object_id:` only the
events about that object (thin events only), plus `limit:` and `after:`. At a provider with two kinds of events, `events:` (`:thin` or `:snapshot`, else the
tenant's `:events`) picks which are read: Stripe's thin events come from API v2
(`/v2/core/events`, 20 a page), each the same Event its webhook gives, named as its snapshot
event (`invoice.paid`), and `types:` takes those names or Stripe's thin ones
(`v1.invoice.paid`); snapshot events from `/v1/events`.

# `list_fraud_reviews`

```elixir
@spec list_fraud_reviews(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the reviews still open, newest first (`MishkaPay.Page` of `MishkaPay.Payment.FraudReview`):
payments the provider's fraud rules hold for the seller, plus `limit:` and `after:`.

# `list_fraud_warnings`

```elixir
@spec list_fraud_warnings(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of early fraud warnings, newest first (`MishkaPay.Page` of `MishkaPay.Payment.FraudWarning`):
`payment_id:` or `charge_id:` only those about one payment, plus `limit:` and `after:`. A
warning that is `:actionable` can still be headed off: refund its payment in full.

# `list_invoice_items`

```elixir
@spec list_invoice_items(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of invoice items at `provider`, newest first (`MishkaPay.Page` of
`MishkaPay.Invoice.Item`): `customer_id:` one customer's, `invoice_id:` those on one bill,
`pending: true` only those still waiting for a bill, plus `limit:` and `after:`.

# `list_invoices`

```elixir
@spec list_invoices(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of invoices at `provider`, newest first (`MishkaPay.Page`): `subscription_id:` one
subscription's, or `customer_id:` one customer's, plus `limit:` and `after:`.

# `list_meters`

```elixir
@spec list_meters(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of meters at `provider` (`MishkaPay.Page`): `status:` only `:active` or `:inactive`
ones, plus `limit:` and `after:`.

# `list_payment_links`

```elixir
@spec list_payment_links(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of payment links at `provider`, newest first (`MishkaPay.Page`): `active:` only those
on (or off), plus `limit:` and `after:`.

# `list_payment_methods`

```elixir
@spec list_payment_methods(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the payment methods customer `customer_id:` saved at `provider`
(`MishkaPay.Page` of `MishkaPay.Customer.PaymentMethod`), plus `limit:` and `after:`. A checkout in
`mode: :setup` saves one.

# `list_payments`

```elixir
@spec list_payments(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of payments at `provider`, newest first (`MishkaPay.Page`): `customer_id:` only one
customer's, plus `limit:` and `after:`. Each is a `MishkaPay.Payment` as `fetch_payment/3`
answers it.

# `list_payouts`

```elixir
@spec list_payouts(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of payouts, newest first (`MishkaPay.Page` of `MishkaPay.Balance.Payout`): `status:` only
`:pending`, `:in_transit`, `:paid`, `:failed` or `:canceled` ones, plus `limit:` and `after:`.

# `list_portal_configurations`

```elixir
@spec list_portal_configurations(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of portal setups at `provider`, newest first (`MishkaPay.Page` of
`MishkaPay.PortalSession.Configuration`): `active:` only those on (or off), `default: true` only the one
a session without `:configuration` uses, plus `limit:` and `after:`.

# `list_prices`

```elixir
@spec list_prices(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of prices at `provider`, newest first (`MishkaPay.Page`): `product_id:` only one
product's, `lookup_key:` the price the host named so, `active:` only those on (or off) sale,
plus `limit:` and `after:`.

# `list_products`

```elixir
@spec list_products(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of products at `provider`, newest first (`MishkaPay.Page`): `active:` only those on (or
off) sale, plus `limit:` and `after:`.

# `list_promotion_codes`

```elixir
@spec list_promotion_codes(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of promotion codes at `provider`, newest first (`MishkaPay.Page`): `code:` the code a
buyer typed, `coupon_id:` only those of one coupon, `active:` only those that can (or cannot)
be used now, plus `limit:` and `after:`.

# `list_refunds`

```elixir
@spec list_refunds(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of refunds at `provider`, newest first (`MishkaPay.Page`): `payment_id:` only one
payment's, plus `limit:` and `after:`.

# `list_shipping_rates`

```elixir
@spec list_shipping_rates(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of shipping rates at `provider`, newest first (`MishkaPay.Page`): `active:` only those
that can (or cannot) be offered, plus `limit:` and `after:`.

# `list_subscription_schedules`

```elixir
@spec list_subscription_schedules(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of subscription schedules at `provider`, newest first (`MishkaPay.Page` of
`MishkaPay.Subscription.Schedule`): `customer_id:` one customer's, `scheduled: true` only those
not started yet, plus `limit:` and `after:`.

# `list_subscriptions`

```elixir
@spec list_subscriptions(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of subscriptions at `provider`, newest first (`MishkaPay.Page` of
`MishkaPay.Subscription`): `customer_id:` one customer's, `price_id:` those that charge a price,
`status:` those in one status (`MishkaPay.Subscription.statuses/0`) or `:all`, plus `limit:`
and `after:`. Without `status:` a provider may leave ended ones out (Stripe does). The provider
needs `:subscription_list`.

# `list_tax_ids`

```elixir
@spec list_tax_ids(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of customer `customer_id`'s tax ids at `provider` (`MishkaPay.Page` of
`MishkaPay.Customer.TaxId`), with `limit:` and `after:`.

# `list_tax_rates`

```elixir
@spec list_tax_rates(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of `provider`'s tax rates, newest first (`MishkaPay.Page` of `MishkaPay.TaxRate`):
`active: true` or `false`, `inclusive: true` or `false`, plus `limit:` and `after:`.

# `list_tax_registrations`

```elixir
@spec list_tax_registrations(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the seller's tax registrations (`MishkaPay.Page` of `MishkaPay.TaxSettings.Registration`):
`status:` `:active` (the provider's default), `:scheduled`, `:expired` or `:all`, plus `limit:`
and `after:`.

# `list_transfers`

```elixir
@spec list_transfers(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of the platform's transfers, newest first (`MishkaPay.Page` of `MishkaPay.Transfer`):
`destination:` only those to one connected account, `transfer_group:` one order's, plus
`limit:` and `after:`.

# `login_link`

```elixir
@spec login_link(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.ConnectedAccount.Link.t()} | {:error, Splode.Error.t()}
```

Makes a one-time link into connected account `account_id`'s own dashboard at the provider
(`MishkaPay.ConnectedAccount.Link`, `type: :login`), for a seller who finished onboarding.

# `mark_invoice_uncollectible`

```elixir
@spec mark_invoice_uncollectible(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

Marks open bill `invoice_id` as one that will not be paid; it can still be paid later.

# `pause_collection`

```elixir
@spec pause_collection(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

Pauses collecting subscription `subscription_id`'s payments; the subscription stays. `behavior:`
`:void` (the default: its invoices are voided), `:keep_as_draft` or `:mark_uncollectible`;
`resumes_at:` when collection starts again by itself.

# `pay_invoice`

```elixir
@spec pay_invoice(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

Settles open bill `invoice_id`: charges the customer's saved payment method now, or with
`out_of_band: true` marks it paid by other means (cash, a bank transfer seen by hand).

# `portal_session`

```elixir
@spec portal_session(map()) ::
  {:ok, MishkaPay.PortalSession.t()} | {:error, Splode.Error.t()}
```

Opens the provider's billing page for one customer (see `MishkaPay.PortalSession`): `:provider`,
`:tenant`, `:customer_id`, `:return_url`, and `:configuration`, the `:id` of a
`MishkaPay.PortalSession.Configuration` (the provider's default one when left out). Redirect the buyer
to the answer's `:url`.

# `preview_credit_note`

```elixir
@spec preview_credit_note(map()) ::
  {:ok, MishkaPay.CreditNote.t()} | {:error, Splode.Error.t()}
```

The credit note `create_credit_note/1` would make with the same `attrs`, with its amount, tax
and lines, without making it.

# `preview_subscription_change`

```elixir
@spec preview_subscription_change(map()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

The invoice `change_subscription/1` would make with the same `attrs`, with its proration lines,
without changing anything. When the change prorates and `attrs` has no `:proration_date`, it
counts from now: give the same `:proration_date` to both calls to bill exactly the preview.

# `reactivate_meter`

```elixir
@spec reactivate_meter(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Meter.t()} | {:error, Splode.Error.t()}
```

Turns meter `meter_id` on again after `deactivate_meter/3`: it takes usage and prices again.

# `record_tax`

```elixir
@spec record_tax(String.t(), String.t(), String.t(), term()) ::
  {:ok, MishkaPay.TaxCalculation.Transaction.t()} | {:error, Splode.Error.t()}
```

Records the sale counted by tax calculation `calculation_id` under the caller's `reference`
(an order id, one sale per reference), so the provider counts its tax in the site's tax
reports. A calculation can be recorded until its `:expires_at`.

# `refund`

```elixir
@spec refund(map()) :: {:ok, MishkaPay.Refund.t()} | {:error, Splode.Error.t()}
```

Refunds a payment from `attrs` (see `MishkaPay.Refund`), in full or in part.

# `refund_application_fee`

```elixir
@spec refund_application_fee(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.ApplicationFee.t()} | {:error, Splode.Error.t()}
```

Gives application fee `fee_id` back to the seller: all of it, or `amount:` (money in the fee's
currency). `reference:` makes it once. Answers the fee after, with `:amount_refunded`.

# `release_subscription_schedule`

```elixir
@spec release_subscription_schedule(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Subscription.Schedule.t()} | {:error, Splode.Error.t()}
```

Releases subscription schedule `schedule_id`: the schedule ends, and its subscription goes on
as it is now, without the phases still to come.

# `replay_events`

```elixir
@spec replay_events(String.t(), term(), keyword()) ::
  {:ok, %{delivered: non_neg_integer(), failed: [{String.t(), term()}]}}
  | {:error, Splode.Error.t()}
```

Delivers again every event `provider` sent `tenant` since `since:`, to the
`mishka_pay:webhook:received` listeners (`MishkaPay.Webhook.deliver/1`), oldest first: what a
site missed while its webhook endpoint was down. Only the events Mishka Pay acts on are
delivered, when the provider says which: the window is read once, a hundred events a request,
and the others are left out. `types:` names the events to deliver instead, and asks the
provider for only those (Stripe takes 20 types a request). A listener keeps each event once, so
one already taken is not done twice. `events:` reads the thin or the snapshot events, as in
`list_events/3`: replay the kind the site's webhook takes, so the ids match those it kept.

Answers how many were delivered and which failed, by event id.

# `report_usage`

```elixir
@spec report_usage(map()) :: {:ok, MishkaPay.Usage.t()} | {:error, Splode.Error.t()}
```

Reports what a customer used, from `attrs` (see `MishkaPay.Usage`): the meter's
`:event_name`, the `:customer_id`, a `:value`, when it happened (`:at`) and a `:reference`, so
the same use never counts twice.

# `request`

```elixir
@spec request(map()) :: {:ok, map()} | {:error, Splode.Error.t()}
```

Calls any path of the provider's own API with the tenant's keys, for what Mishka Pay has no
typed call for yet, and answers the provider's decoded answer as it is (a map). `attrs` is a
`MishkaPay.RawRequest`: `:method`, `:path` (from the root, never an address), `:params`, a
`:reference` that makes a write's idempotency key, and `:options` (`MishkaPay.RawRequest.Options`:
`:api_version`, `:expand`). It goes through the same retries, idempotency keys and telemetry as
every typed call, and an error is the same `MishkaPay.Errors` one.

    MishkaPay.request(%{provider: "stripe", tenant: site_id, path: "/v1/tax/settings"})

    MishkaPay.request(%{provider: "stripe", tenant: site_id, method: :post,
                        path: "/v1/customers/#{id}", params: %{"preferred_locales" => ["de"]},
                        reference: "locale-#{id}", options: %{expand: ["tax"]}})

Reach for it only until a typed call exists: the answer is the provider's own shape, which
changes with its API version.

# `resume_collection`

```elixir
@spec resume_collection(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

Collects paused subscription `subscription_id`'s payments again.

# `resume_subscription`

```elixir
@spec resume_subscription(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

Takes back a cancel set for the period's end, so subscription `subscription_id` goes on.

# `reverse_transfer`

```elixir
@spec reverse_transfer(String.t(), String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Transfer.t()} | {:error, Splode.Error.t()}
```

Takes transfer `transfer_id` back from its connected account: all of it, or `amount:` (money
in the transfer's currency). `reference:` makes it once. Answers the transfer after, with
`:amount_reversed`.

# `search_customers`

```elixir
@spec search_customers(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of `provider`'s customers that match every filter given (`MishkaPay.Page`): `email:`,
`name:`, `reference:` (the host's own id given when the customer was made), plus `limit:` and
`after:`. A customer just made may take a minute to be found. `api:` (else the tenant's
`:customer_api`) is the API the found customers are named by: Stripe searches its Customers,
which include those made on Accounts v2, and on `:v2` each of those answers its account id.

# `search_subscriptions`

```elixir
@spec search_subscriptions(String.t(), term(), keyword()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

One page of `provider`'s subscriptions that match every filter given (`MishkaPay.Page`):
`status:` (`MishkaPay.Subscription.statuses/0`), `reference:` (the caller's own id from the
checkout), `metadata:` (a map whose pairs must all match), plus `limit:` and `after:`. A
subscription just made may take a minute to be found. The provider needs `:subscription_list`.

# `send_invoice`

```elixir
@spec send_invoice(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

Emails open bill `invoice_id` to its customer, with the provider's page to pay it.

# `set_default_payment_method`

```elixir
@spec set_default_payment_method(String.t(), String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Customer.t()} | {:error, Splode.Error.t()}
```

Makes saved payment method `payment_method_id` the one customer `customer_id`'s invoices and
subscriptions charge, and answers the customer after, with its `:default_payment_method`.

# `upcoming_invoice`

```elixir
@spec upcoming_invoice(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

The bill subscription `subscription_id` will make next, as the provider counts it now.

# `update_connected_account`

```elixir
@spec update_connected_account(map()) ::
  {:ok, MishkaPay.ConnectedAccount.t()} | {:error, Splode.Error.t()}
```

Changes the connected account `attrs` names by `:id`: the `:email`, `:business_name`,
`:configurations` and `:capabilities` (asked for on top of those it has) or `:metadata` given.
Answers it after.

# `update_customer`

```elixir
@spec update_customer(map()) ::
  {:ok, MishkaPay.Customer.t()} | {:error, Splode.Error.t()}
```

Changes customer `attrs.id` at `attrs.provider`: only the fields given are sent.

# `update_dispute`

```elixir
@spec update_dispute(map()) ::
  {:ok, MishkaPay.Dispute.t()} | {:error, Splode.Error.t()}
```

Answers a dispute with evidence (see `MishkaPay.Dispute.Evidence`): kept to add more, or sent to
the bank with `submit: true`. Answers the dispute after.

# `update_invoice_item`

```elixir
@spec update_invoice_item(map()) ::
  {:ok, MishkaPay.Invoice.Item.t()} | {:error, Splode.Error.t()}
```

Changes invoice item `attrs.id` at `attrs.provider`: only the fields given (`:name`,
`:amount`, `:quantity`, `:price_id`, the tax fields, `:metadata`). Its customer and bill stay:
`:customer_id` or `:invoice_id` here is refused.

# `update_meter`

```elixir
@spec update_meter(map()) :: {:ok, MishkaPay.Meter.t()} | {:error, Splode.Error.t()}
```

Renames meter `:id` to `:name` (see `MishkaPay.Meter`). Its event name and how it adds up never
change: make a new meter for that.

# `update_payment_intent`

```elixir
@spec update_payment_intent(map()) ::
  {:ok, MishkaPay.PaymentIntent.t()} | {:error, Splode.Error.t()}
```

Changes payment intent `attrs.id` before it is paid: only the fields given (`:amount`,
`:customer_id`, `:payment_method_id`, `:capture`, `:setup_future_usage`, `:description`,
`:metadata`).

# `update_payment_link`

```elixir
@spec update_payment_link(map()) ::
  {:ok, MishkaPay.PaymentLink.t()} | {:error, Splode.Error.t()}
```

Changes payment link `attrs.id` at `attrs.provider`: `active: false` turns it off and `true` on
again, and any other option given (`:max_purchases`, `:inactive_message`, `:success_url`,
`:allow_promotion_codes`...) is changed too; its prices and trial stay as made. A link cannot be
deleted; a turned-off one refuses buyers.

# `update_portal_configuration`

```elixir
@spec update_portal_configuration(map()) ::
  {:ok, MishkaPay.PortalSession.Configuration.t()} | {:error, Splode.Error.t()}
```

Changes portal setup `attrs.id` at `attrs.provider`: only the fields given. `active: false`
turns it off; a provider never deletes one.

# `update_product`

```elixir
@spec update_product(map()) ::
  {:ok, MishkaPay.Product.t()} | {:error, Splode.Error.t()}
```

Changes product `attrs.id` at `attrs.provider`: only the fields given are sent.

# `update_promotion_code`

```elixir
@spec update_promotion_code(map()) ::
  {:ok, MishkaPay.Coupon.PromotionCode.t()} | {:error, Splode.Error.t()}
```

Changes promotion code `attrs.id` at `attrs.provider`: `active: false` turns it off, `true` on
again; `:metadata` too. Its code, coupon and limits stay as made.

# `update_subscription_schedule`

```elixir
@spec update_subscription_schedule(map()) ::
  {:ok, MishkaPay.Subscription.Schedule.t()} | {:error, Splode.Error.t()}
```

Changes subscription schedule `attrs.id` at `attrs.provider`: only what is given. `:phases`
replaces the phases from the current one on (the current one with the start it has);
`:end_behavior` and `:proration` (how this change is billed) as on
`MishkaPay.Subscription.Schedule`. Its customer and subscription stay.

# `update_tax_rate`

```elixir
@spec update_tax_rate(map()) ::
  {:ok, MishkaPay.TaxRate.t()} | {:error, Splode.Error.t()}
```

Changes tax rate `attrs.id` at `attrs.provider`: only the fields given (`:active`,
`:display_name`, `:description`, the place, `:tax_type`, `:metadata`). `active: false` archives
it. Its `:percentage` and `:inclusive` never change: make a new rate instead.

# `update_tax_settings`

```elixir
@spec update_tax_settings(map()) ::
  {:ok, MishkaPay.TaxSettings.t()} | {:error, Splode.Error.t()}
```

Changes the tax settings of `attrs.tenant` at `attrs.provider` (see `MishkaPay.TaxSettings`):
the `:head_office`, the default `:tax_code` and `:tax_behavior`, only those given. Answers them
after, with the `:status` they leave.

# `upload_file`

```elixir
@spec upload_file(map()) :: {:ok, MishkaPay.File.t()} | {:error, Splode.Error.t()}
```

Uploads a file from `attrs` (see `MishkaPay.File.Upload`): a receipt, a download log or a
screenshot that answers a dispute. Answers it as a `MishkaPay.File`; put its `:id` in the
dispute's evidence with `update_dispute/1`.

# `usage_summary`

```elixir
@spec usage_summary(
  String.t(),
  String.t(),
  String.t(),
  DateTime.t(),
  DateTime.t(),
  term()
) ::
  {:ok, MishkaPay.Usage.Summary.t()} | {:error, Splode.Error.t()}
```

What meter `meter_id` counted for `customer_id` from `from` to `to` (`DateTime`s, `to` not
included), as one `MishkaPay.Usage.Summary`. A use reported a moment ago may not be counted yet.

# `void_credit_note`

```elixir
@spec void_credit_note(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.CreditNote.t()} | {:error, Splode.Error.t()}
```

Voids credit note `credit_note_id`: it stays on record and credits nothing. A provider may
void one only while its bill is open (Stripe does).

# `void_invoice`

```elixir
@spec void_invoice(String.t(), String.t(), term()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

Voids open bill `invoice_id`: it stays on record and can no longer be paid.

---

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