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

Every payment provider, Stripe included, implements these callbacks. A provider is one module:

    defmodule MyApp.Pay.Acme do
      use MishkaPay.Provider,
        id: "acme",
        label: "Acme Pay",
        capabilities: [:checkout, :refund, :webhook]
    end

Supervise the module in the application that ships it, like any other mishka_installer plugin.
`use` makes it a plugin on the `mishka_pay:providers` event (`MishkaPay.Events.providers/0`): it
adds itself to the `providers` list the event carries. Supervising it installs the provider, and
stopping its plugin in the installer takes it out. A project adds its own payment method the same
way, without changing Mishka Pay.

## Options of `use`

  * `:id` (required): a short lowercase name, such as `"stripe"`. Every call names the provider by it.
  * `:label` (required): the name a person reads.
  * `:capabilities`: what the provider can do, from `t:capability/0`. A call to something not
    listed answers a `MishkaPay.Errors.Unsupported` error without reaching the provider.
  * `:priority`: the plugin's priority on the event, 50 by default. When two installed providers
    share an id, the one that comes first wins.

## Which providers are installed

`all/0`, `offered/0` and `fetch/1` ask the event every time, so mishka_installer's own registry is
the only list and nothing is cached. A module counts only when it implements every required
callback. When a plugin of the event is registered but not loaded, the event cannot run and no
provider can be told installed: `fetch/1` then answers a `MishkaPay.Errors.UnknownProvider` error
with the reason `:cannot_run`.

The same pattern as `MishkaCmsCore.ProviderRegistry` and `MishkaCmsCore.Captcha.Provider`.

## Operations

Each capability brings the callbacks it needs, and a provider that declares a capability without
them does not compile:

  * `:checkout`: `checkout/2`, `fetch_checkout/2` and `fetch_payment/2`;
  * `:embedded_checkout`: nothing more; `checkout/2` also takes `ui_mode: :embedded`;
  * `:capture`: `capture_payment/3`, `cancel_payment/2` (`checkout/2` also takes
    `capture: :manual`);
  * `:expire`: `expire_checkout/2`;
  * `:intent`: `create_payment_intent/2`, `fetch_payment_intent/2`, `update_payment_intent/2`,
    `confirm_payment_intent/3`, `cancel_payment_intent/2`, `create_setup_intent/2`,
    `fetch_setup_intent/2`, `confirm_setup_intent/3`, `cancel_setup_intent/2`;
  * `:payment_list`: `list_payments/2`;
  * `:refund`: `refund/2`;
  * `:refund_read`: `fetch_refund/2`, `list_refunds/2`;
  * `:subscription`: `fetch_subscription/2`, `cancel_subscription/3`, `resume_subscription/2`,
    `list_invoices/2`, `fetch_invoice/2` and `upcoming_invoice/2` (a subscription starts with a checkout in
    `mode: :subscription`);
  * `:subscription_change`: `change_subscription/2`, `preview_subscription_change/2`,
    `pause_collection/3`, `resume_collection/2`;
  * `:subscription_list`: `list_subscriptions/2`, `search_subscriptions/2`;
  * `:subscription_schedule`: `create_subscription_schedule/2`,
    `fetch_subscription_schedule/2`, `list_subscription_schedules/2`,
    `update_subscription_schedule/2`, `release_subscription_schedule/2`,
    `cancel_subscription_schedule/3`;
  * `:invoice`: `create_invoice/2`, `finalize_invoice/2`, `send_invoice/2`, `pay_invoice/3`,
    `void_invoice/2`, `mark_invoice_uncollectible/2`, `delete_invoice/2`;
  * `:invoice_item`: `create_invoice_item/2`, `update_invoice_item/2`, `delete_invoice_item/2`,
    `list_invoice_items/2`;
  * `:credit_note`: `create_credit_note/2`, `preview_credit_note/2`, `fetch_credit_note/2`,
    `void_credit_note/2`, `list_credit_notes/2`, `list_credit_note_lines/3`;
  * `:customer`: `create_customer/2`, `fetch_customer/2`, `update_customer/2`, `list_customers/2`,
    `search_customers/2`, `delete_customer/2`;
  * `:tax_id`: `create_tax_id/2`, `list_tax_ids/2`, `delete_tax_id/3`;
  * `:tax`: `calculate_tax/2`, `record_tax/3`;
  * `:tax_rate`: `create_tax_rate/2`, `fetch_tax_rate/2`, `update_tax_rate/2`,
    `list_tax_rates/2` (and a line's or a bill's `:tax_rate_ids`);
  * `:tax_setup`: `create_tax_registration/2`, `list_tax_registrations/2`,
    `expire_tax_registration/3`, `fetch_tax_settings/1`, `update_tax_settings/2`;
  * `:shipping`: `create_shipping_rate/2`, `list_shipping_rates/2` (and a checkout's
    `:shipping_countries` and `:shipping_rates`);
  * `:portal`: `portal_session/2`, and the portal's setups: `create_portal_configuration/2`,
    `update_portal_configuration/2`, `fetch_portal_configuration/2`,
    `list_portal_configurations/2`;
  * `:payment_method`: `list_payment_methods/2`, `fetch_payment_method/2`,
    `detach_payment_method/2`, `set_default_payment_method/3` (a checkout in `mode: :setup`
    saves one);
  * `:discount`: coupons and promotion codes (`create_coupon/2` and the rest);
  * `:catalog`: products and prices (`create_product/2` and the rest);
  * `:payment_link`: `create_payment_link/2`, `fetch_payment_link/2`, `list_payment_links/2`,
    `update_payment_link/2`;
  * `:dispute`: `fetch_dispute/2`, `list_disputes/2`, `update_dispute/2`, `accept_dispute/2`;
  * `:fraud`: `fetch_fraud_warning/2`, `list_fraud_warnings/2`, `fetch_fraud_review/2`,
    `list_fraud_reviews/2`, `approve_fraud_review/2`;
  * `:file`: `upload_file/2`, `fetch_file/2`, `file_link/3`;
  * `:usage`: `create_meter/2`, `fetch_meter/2`, `update_meter/2`, `list_meters/2`,
    `deactivate_meter/2`, `reactivate_meter/2`, `report_usage/2`, `cancel_usage/2`,
    `usage_summary/3`;
  * `:entitlement`: `create_feature/2`, `attach_feature/3`, `list_entitlements/2`;
  * `:balance`: `fetch_balance/1`, `list_balance_transactions/2`;
  * `:customer_balance`: `adjust_customer_balance/2`, `list_customer_balance/2`;
  * `:connect`: `create_connected_account/2`, `fetch_connected_account/3`,
    `update_connected_account/2`, `list_connected_accounts/2`, `close_connected_account/3`,
    `account_link/2`, `login_link/2`, `fetch_application_fee/2`, `list_application_fees/2`,
    `refund_application_fee/3` (and a checkout's `:application_fee`,
    `:application_fee_percent`, `:destination` and `:on_behalf_of`);
  * `:transfer`: `create_transfer/2`, `fetch_transfer/2`, `list_transfers/2`,
    `reverse_transfer/3`;
  * `:payout`: `fetch_payout/2`, `list_payouts/2`, `cancel_payout/2`;
  * `:webhook`: `verify_webhook/3`;
  * `:event_list`: `list_events/2`;
  * `:raw_request`: `raw_request/2`.

Every `list_*` callback takes the list options (`:limit`, 1 to 100; `:after`, the cursor of a
page before; and its own filters) and answers one `MishkaPay.Page`.

Every operation takes a guarded_struct and the tenant's `MishkaPay.Credentials`, and answers a
guarded_struct or a `MishkaPay.Errors` error. A project calls them through `MishkaPay`, which
checks the capability, asks for the keys and emits telemetry first.

# `capability`

```elixir
@type capability() ::
  :checkout
  | :embedded_checkout
  | :capture
  | :expire
  | :intent
  | :refund
  | :refund_read
  | :subscription
  | :subscription_change
  | :subscription_list
  | :subscription_schedule
  | :invoice
  | :invoice_item
  | :credit_note
  | :customer
  | :tax_id
  | :tax
  | :tax_rate
  | :tax_setup
  | :shipping
  | :portal
  | :payment_method
  | :discount
  | :catalog
  | :payment_link
  | :dispute
  | :fraud
  | :file
  | :usage
  | :entitlement
  | :balance
  | :customer_balance
  | :connect
  | :transfer
  | :payout
  | :payment_list
  | :webhook
  | :event_list
  | :raw_request
  | :return_verify
```

What a provider can do:

  * `:checkout`: sends the buyer to pay, or embeds a payment form.
  * `:embedded_checkout`: shows its checkout form inside the site's own page
    (`ui_mode: :embedded`).
  * `:capture`: holds the money on a card at checkout (`capture: :manual`), then takes it, all
    or part, or lets it go.
  * `:expire`: ends an open checkout before the buyer pays, so its stock is free again.
  * `:intent`: takes a payment, or saves a payment method, with its own card form inside the
    site's page (Stripe Elements), without a checkout page: the server makes the intent, the
    buyer's browser confirms it with its client secret, and the server reads, changes, confirms
    or cancels it.
  * `:payment_list`: lists past payments page by page.
  * `:refund`: gives money back on a payment.
  * `:refund_read`: reads a refund again, and lists refunds page by page.
  * `:subscription`: charges again on a schedule.
  * `:subscription_change`: changes a running subscription's plan or quantity with proration,
    previews what that bills, and pauses or resumes its collection.
  * `:subscription_list`: lists subscriptions page by page (by customer, status or price), and
    searches them by status, reference or metadata. A provider can run subscriptions without
    it: PayPal has no list of them.
  * `:subscription_schedule`: plans a subscription's changes ahead in phases (a new price on a
    date, a trial, an end after some periods), made from a running subscription or new, and
    changes, releases or cancels the plan.
  * `:invoice`: makes one-off bills for a customer, and opens, sends, settles or ends them.
  * `:invoice_item`: keeps charges on their own (add, change, remove, list) that wait for a
    customer's next bill, or go on a draft one. Apart from `:invoice`: a provider may bill
    without keeping charges between bills (PayPal's invoices hold their items only inside one).
  * `:credit_note`: takes back part or all of a finalized bill with a credit note (by amount or
    by line, refunded, credited to the customer's balance or settled outside), previews one,
    reads, lists and voids them.
  * `:customer`: keeps buyers (create, read, update, list, delete).
  * `:tax_id`: keeps a business buyer's tax ids (EU VAT and the rest) on its customer.
  * `:tax`: counts the tax on a sale made outside its checkout, and records the sale for the
    site's tax reports.
  * `:tax_rate`: keeps tax rates the seller sets by hand (a percentage, inclusive or on top,
    for a place), and adds them to the lines of its checkouts and bills. Apart from `:tax`: a
    provider may take fixed rates without counting any tax itself.
  * `:tax_setup`: keeps where the seller is registered to collect tax, and the site's tax
    settings (head office, the default tax code and behavior) that its tax counting uses.
    Apart from `:tax`: a provider that counts the tax as the merchant of record has no
    registrations of the seller's to keep.
  * `:shipping`: keeps shipping rates, and its checkout asks for a shipping address and
    charges the rate the buyer picks.
  * `:portal`: has a hosted page where a customer manages their own billing, and keeps setups
    of what buyers may do there.
  * `:payment_method`: keeps a customer's saved payment methods (read, list, take off, make
    the default), and saves one with a checkout in `mode: :setup`.
  * `:discount`: keeps coupons and the promotion codes buyers type.
  * `:catalog`: keeps products and their prices, so a checkout sells a price by its id.
  * `:payment_link`: makes pages that sell catalog prices to anyone who opens them.
  * `:dispute`: reads chargebacks and answers them with evidence, or accepts them.
  * `:fraud`: reads a card issuer's early fraud warnings, and the payments its fraud rules hold
    for review, which the seller lets through.
  * `:file`: keeps files, such as dispute evidence, and makes public links to them.
  * `:usage`: counts what customers use on meters, for prices billed by usage, and takes back
    a report sent by mistake.
  * `:entitlement`: attaches features to products and tells which ones a customer may use.
  * `:balance`: reads the seller's balance and the movements that made it.
  * `:customer_balance`: keeps a customer's store credit, taken off their next bills.
  * `:connect`: runs a platform of sellers: makes their connected accounts and the links that
    onboard them, acts for one when a tenant's keys name it (`:account_id`), takes the
    platform's cut of their sales (a checkout's `:application_fee`, `:destination`,
    `:on_behalf_of`) and gives it back.
  * `:transfer`: sends money from the platform's balance to a connected account, and takes it
    back.
  * `:payout`: reads the payouts of an account's balance to its bank, and stops a pending one.
  * `:webhook`: sends signed messages when something changes.
  * `:event_list`: lists the messages it sent, to deliver again those a site missed.
  * `:raw_request`: calls any path of its own API with the tenant's keys, for what Mishka Pay
    has no typed call for yet (`MishkaPay.request/1`).
  * `:return_verify`: has no webhook; the buyer comes back to a return URL and the payment is
    checked with a call to the provider.

# `accept_dispute`
*optional* 

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

With `:dispute`. Accepts the loss: the dispute closes as lost.

# `account_link`
*optional* 

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

With `:connect`. Makes a one-time onboarding or update link for a connected account.

# `adjust_customer_balance`
*optional* 

```elixir
@callback adjust_customer_balance(
  MishkaPay.Customer.BalanceTransaction.t(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Customer.BalanceTransaction.t()} | {:error, Splode.Error.t()}
```

With `:customer_balance`. Changes a customer's balance: below zero gives credit.

# `approve_fraud_review`
*optional* 

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

With `:fraud`. Lets an open review's payment through, and answers the review closed.

# `attach_feature`
*optional* 

```elixir
@callback attach_feature(
  product_id :: String.t(),
  feature_id :: String.t(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Feature.t()} | {:error, Splode.Error.t()}
```

With `:entitlement`. Attaches a feature to a catalog product, and answers the feature.

# `calculate_tax`
*optional* 

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

With `:tax`. Counts the tax on the calculation's lines and shipping for the buyer's address or
customer, and answers it with its `:id`, totals and the tax of each line.

# `cancel_payment`
*optional* 

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

With `:capture`. Lets the money held on an `:authorized` payment go; it ends `:canceled`.

# `cancel_payment_intent`
*optional* 

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

With `:intent`. Cancels a payment intent that is not paid, or lets a held one go.

# `cancel_payout`
*optional* 

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

With `:payout`. Stops a payout that is still pending; its money stays in the balance.

# `cancel_setup_intent`
*optional* 

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

With `:intent`. Cancels a setup intent that has not succeeded.

# `cancel_subscription`
*optional* 

```elixir
@callback cancel_subscription(
  subscription_id :: String.t(),
  at :: :now | :period_end,
  MishkaPay.Credentials.t()
) :: {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

With `:subscription`. Cancels a subscription `:now`, or at the end of the period paid for
(`:period_end`), and answers it as the provider has it after.

# `cancel_subscription_schedule`
*optional* 

```elixir
@callback cancel_subscription_schedule(
  schedule_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) :: {:ok, MishkaPay.Subscription.Schedule.t()} | {:error, Splode.Error.t()}
```

With `:subscription_schedule`. Ends the schedule and its subscription now; `:invoice_now` bills
what is left, `:prorate` credits time not used.

# `cancel_usage`
*optional* 

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

With `:usage`. Takes back one usage report by its id (`:usage_id`) under `:event_name`, once
for each report, and answers it with its `:status`.

# `capabilities`

```elixir
@callback capabilities() :: [capability()]
```

What the provider can do. Set by `use`.

# `capture_payment`
*optional* 

```elixir
@callback capture_payment(
  payment_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Payment.t()} | {:error, Splode.Error.t()}
```

With `:capture`. Takes the money held on an `:authorized` payment: all of it, or `:amount`
(a `Money` in the payment's currency) when given. The rest is let go. Answers the payment after.

# `change_subscription`
*optional* 

```elixir
@callback change_subscription(
  MishkaPay.Subscription.Change.t(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

With `:subscription_change`. Changes a subscription's plan or quantity as the change says,
bills the difference its way, and answers the subscription after.

# `check_keys`
*optional* 

```elixir
@callback check_keys(MishkaPay.Credentials.t()) :: :ok | {:error, Splode.Error.t()}
```

Optional. Whether the provider takes `keys`, with one read call that changes nothing
(`MishkaPay.Check`).

# `checkout`
*optional* 

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

With `:checkout`. Opens a checkout at the provider with the tenant's keys and answers it with
the provider's `:id`, `:url` and `:status` filled in.

# `close_connected_account`
*optional* 

```elixir
@callback close_connected_account(
  account_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.ConnectedAccount.t()} | {:error, Splode.Error.t()}
```

With `:connect`. Closes a connected account for good: it takes no more payments or payouts.
`opts` may name the `:api`, and a `:reason` where the provider takes one.

# `confirm_payment_intent`
*optional* 

```elixir
@callback confirm_payment_intent(
  payment_intent_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) :: {:ok, MishkaPay.PaymentIntent.t()} | {:error, Splode.Error.t()}
```

With `:intent`. Confirms a payment intent on the server, with `:payment_method_id` and the
`:return_url` a payment method's own page sends the buyer back to.

# `confirm_setup_intent`
*optional* 

```elixir
@callback confirm_setup_intent(
  setup_intent_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.SetupIntent.t()} | {:error, Splode.Error.t()}
```

With `:intent`. Confirms a setup intent on the server, as `confirm_payment_intent/3`.

# `create_connected_account`
*optional* 

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

With `:connect`. Makes a connected account for a seller; its `:reference` makes the
idempotency key.

# `create_coupon`
*optional* 

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

With `:discount`. Makes a coupon and answers it with its `:id`.

# `create_credit_note`
*optional* 

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

With `:credit_note`. Makes a credit note on `:invoice_id` for `:amount` or `:lines`, and
answers it with its `:id`.

# `create_customer`
*optional* 

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

With `:customer`. Makes a customer at the provider and answers it with its `:id`, on the
customer's `:api`, else the tenant's `:customer_api`, at a provider with two.

# `create_feature`
*optional* 

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

With `:entitlement`. Makes a feature a product can give.

# `create_invoice`
*optional* 

```elixir
@callback create_invoice(MishkaPay.Invoice.Draft.t(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

With `:invoice`. Makes a draft bill with its items, and answers it.

# `create_invoice_item`
*optional* 

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

With `:invoice_item`. Adds a charge for `:customer_id`, on draft bill `:invoice_id` or waiting
for the next bill, and answers it with its `:id`.

# `create_meter`
*optional* 

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

With `:usage`. Makes a meter that counts usage reported under its event name.

# `create_payment_intent`
*optional* 

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

With `:intent`. Makes a payment intent for the site's own card form, and answers it with its
`:id` and `:client_secret`.

# `create_payment_link`
*optional* 

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

With `:payment_link`. Makes a payment link and answers it with its `:id` and `:url`.

# `create_portal_configuration`
*optional* 

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

With `:portal`. Makes a portal setup and answers it with its `:id`.

# `create_price`
*optional* 

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

With `:catalog`. Makes a price of a product (`:product_id`) and answers it with its `:id`.

# `create_product`
*optional* 

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

With `:catalog`. Makes a product and answers it with its `:id`.

# `create_promotion_code`
*optional* 

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

With `:discount`. Makes a promotion code for a coupon and answers it with its `:id`.

# `create_setup_intent`
*optional* 

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

With `:intent`. Makes a setup intent that saves a payment method with the site's own form, and
answers it with its `:id` and `:client_secret`.

# `create_shipping_rate`
*optional* 

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

With `:shipping`. Makes a shipping rate and answers it with its `:id`.

# `create_subscription_schedule`
*optional* 

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

With `:subscription_schedule`. Makes a schedule from `:subscription_id`, or for `:customer_id`
with its `:phases`, and answers it with its `:id` and phase dates.

# `create_tax_id`
*optional* 

```elixir
@callback create_tax_id(MishkaPay.Customer.TaxId.t(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Customer.TaxId.t()} | {:error, Splode.Error.t()}
```

With `:tax_id`. Adds a tax id to the customer it names (`:customer_id`), and answers it.

# `create_tax_rate`
*optional* 

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

With `:tax_rate`. Makes a tax rate, and answers it with its `:id`.

# `create_tax_registration`
*optional* 

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

With `:tax_setup`. Registers the seller to collect tax in a country, and answers it.

# `create_transfer`
*optional* 

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

With `:transfer`. Sends money to a connected account; its `:reference` makes it once.

# `deactivate_meter`
*optional* 

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

With `:usage`. Turns a meter off: it takes no more usage and no new price.

# `delete_coupon`
*optional* 

```elixir
@callback delete_coupon(coupon_id :: String.t(), MishkaPay.Credentials.t()) ::
  :ok | {:error, Splode.Error.t()}
```

With `:discount`. Removes a coupon so it can no longer be applied.

# `delete_customer`
*optional* 

```elixir
@callback delete_customer(customer_id :: String.t(), MishkaPay.Credentials.t()) ::
  :ok | {:error, Splode.Error.t()}
```

With `:customer`. Deletes a customer at the provider for good, as a person's erase request
asks: what the provider keeps on them (saved cards, running subscriptions) goes with it.

# `delete_invoice`
*optional* 

```elixir
@callback delete_invoice(invoice_id :: String.t(), MishkaPay.Credentials.t()) ::
  :ok | {:error, Splode.Error.t()}
```

With `:invoice`. Deletes a draft bill.

# `delete_invoice_item`
*optional* 

```elixir
@callback delete_invoice_item(invoice_item_id :: String.t(), MishkaPay.Credentials.t()) ::
  :ok | {:error, Splode.Error.t()}
```

With `:invoice_item`. Removes an item that is not on a finalized bill.

# `delete_tax_id`
*optional* 

```elixir
@callback delete_tax_id(
  customer_id :: String.t(),
  tax_id_id :: String.t(),
  MishkaPay.Credentials.t()
) ::
  :ok | {:error, Splode.Error.t()}
```

With `:tax_id`. Removes one tax id from a customer.

# `detach_payment_method`
*optional* 

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

With `:payment_method`. Takes a payment method off its customer for good, and answers it
after, with no `:customer_id`.

# `expire_checkout`
*optional* 

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

With `:expire`. Ends an open checkout so it can no longer be paid, and answers it after.

# `expire_tax_registration`
*optional* 

```elixir
@callback expire_tax_registration(
  registration_id :: String.t(),
  at :: DateTime.t() | nil,
  MishkaPay.Credentials.t()
) :: {:ok, MishkaPay.TaxSettings.Registration.t()} | {:error, Splode.Error.t()}
```

With `:tax_setup`. Ends a tax registration `at` a time (`nil`: now), and answers it.

# `fetch_application_fee`
*optional* 

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

With `:connect`. Reads one application fee, the platform's cut of a seller's sale.

# `fetch_balance`
*optional* 

```elixir
@callback fetch_balance(MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Balance.t()} | {:error, Splode.Error.t()}
```

With `:balance`. The seller's balance, available and pending, in each currency.

# `fetch_checkout`
*optional* 

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

With `:checkout`. Reads a checkout again by its id, as the buyer comes back to the success page:
what the provider fills in (`:id`, `:url`, `:status`, `:payment_id`), with `:provider` and the
caller's `:reference`. Its items and URLs stay empty.

# `fetch_connected_account`
*optional* 

```elixir
@callback fetch_connected_account(
  account_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.ConnectedAccount.t()} | {:error, Splode.Error.t()}
```

With `:connect`. Reads one connected account; `opts` may name the `:api` to read it with.

# `fetch_coupon`
*optional* 

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

With `:discount`. Reads one coupon again.

# `fetch_credit_note`
*optional* 

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

With `:credit_note`. Reads one credit note again, with its lines.

# `fetch_customer`
*optional* 

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

With `:customer`. Reads one customer again, on the API its id belongs to.

# `fetch_dispute`
*optional* 

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

With `:dispute`. Reads one dispute.

# `fetch_file`
*optional* 

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

With `:file`. Reads one file the provider keeps.

# `fetch_fraud_review`
*optional* 

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

With `:fraud`. Reads one review, open or closed.

# `fetch_fraud_warning`
*optional* 

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

With `:fraud`. Reads one early fraud warning.

# `fetch_invoice`
*optional* 

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

With `:subscription`. Reads one invoice, with its lines.

# `fetch_meter`
*optional* 

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

With `:usage`. Reads one meter again.

# `fetch_payment`
*optional* 

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

With `:checkout`. Reads one payment again from the provider, its source of truth.

# `fetch_payment_intent`
*optional* 

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

With `:intent`. Reads one payment intent, with its status.

# `fetch_payment_link`
*optional* 

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

With `:payment_link`. Reads one payment link again.

# `fetch_payment_method`
*optional* 

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

With `:payment_method`. Reads one saved payment method again.

# `fetch_payout`
*optional* 

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

With `:payout`. Reads one payout of the account the keys act for.

# `fetch_portal_configuration`
*optional* 

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

With `:portal`. Reads one portal setup.

# `fetch_price`
*optional* 

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

With `:catalog`. Reads one price again.

# `fetch_product`
*optional* 

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

With `:catalog`. Reads one product again.

# `fetch_promotion_code`
*optional* 

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

With `:discount`. Reads one promotion code again.

# `fetch_refund`
*optional* 

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

With `:refund_read`. Reads one refund again, with its status.

# `fetch_setup_intent`
*optional* 

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

With `:intent`. Reads one setup intent, with its status.

# `fetch_subscription`
*optional* 

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

With `:subscription`. Reads one subscription again from the provider.

# `fetch_subscription_schedule`
*optional* 

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

With `:subscription_schedule`. Reads one schedule again, with its phases.

# `fetch_tax_rate`
*optional* 

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

With `:tax_rate`. Reads one tax rate, archived or not.

# `fetch_tax_settings`
*optional* 

```elixir
@callback fetch_tax_settings(MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.TaxSettings.t()} | {:error, Splode.Error.t()}
```

With `:tax_setup`. Reads the site's tax settings.

# `fetch_transfer`
*optional* 

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

With `:transfer`. Reads one transfer.

# `file_link`
*optional* 

```elixir
@callback file_link(file_id :: String.t(), opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.File.Link.t()} | {:error, Splode.Error.t()}
```

With `:file`. Makes a public link to a file; `:expires_at` ends it.

# `finalize_invoice`
*optional* 

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

With `:invoice`. Opens a draft for payment: it gets its number and can be paid.

# `id`

```elixir
@callback id() :: String.t()
```

The provider's id, such as `"stripe"`. Set by `use`.

# `label`

```elixir
@callback label() :: String.t()
```

The name a person reads. Set by `use`.

# `list_application_fees`
*optional* 

```elixir
@callback list_application_fees(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:connect`. One page of application fees, newest first; only `:charge_id`'s when given.

# `list_balance_transactions`
*optional* 

```elixir
@callback list_balance_transactions(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:balance`. One page of the balance's movements, newest first; only those a `:payout_id`
paid out, or of `:type`, when given.

# `list_connected_accounts`
*optional* 

```elixir
@callback list_connected_accounts(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:connect`. One page of the platform's connected accounts, newest first.

# `list_coupons`
*optional* 

```elixir
@callback list_coupons(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:discount`. One page of coupons, newest first.

# `list_credit_note_lines`
*optional* 

```elixir
@callback list_credit_note_lines(
  credit_note_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:credit_note`. One page of a credit note's lines (`MishkaPay.CreditNote.Lines`).

# `list_credit_notes`
*optional* 

```elixir
@callback list_credit_notes(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:credit_note`. One page of credit notes, newest first; only those on `:invoice_id` or of
`:customer_id` when given.

# `list_customer_balance`
*optional* 

```elixir
@callback list_customer_balance(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:customer_balance`. One page of the changes to `:customer_id`'s balance, newest first.

# `list_customers`
*optional* 

```elixir
@callback list_customers(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:customer`. One page of customers, newest first; only those with `:email` when given, on
`:api`, else the tenant's `:customer_api`, at a provider with two.

# `list_disputes`
*optional* 

```elixir
@callback list_disputes(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:dispute`. One page of disputes, newest first; only `:payment_id`'s when given.

# `list_entitlements`
*optional* 

```elixir
@callback list_entitlements(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:entitlement`. One page of the features `:customer_id` may use now.

# `list_events`
*optional* 

```elixir
@callback list_events(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:event_list`. One page of the provider's events, newest first: `:since` (a `DateTime`)
and `:types` (a list of event types) filter them.

# `list_fraud_reviews`
*optional* 

```elixir
@callback list_fraud_reviews(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:fraud`. One page of the reviews still open, newest first.

# `list_fraud_warnings`
*optional* 

```elixir
@callback list_fraud_warnings(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:fraud`. One page of early fraud warnings, newest first; only those about `:payment_id`
or `:charge_id` when given.

# `list_invoice_items`
*optional* 

```elixir
@callback list_invoice_items(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:invoice_item`. One page of items, newest first; only those of `:customer_id`, on
`:invoice_id`, or waiting for a bill (`pending: true`) when given.

# `list_invoices`
*optional* 

```elixir
@callback list_invoices(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:subscription`. One page of invoices, newest first: those of `:subscription_id` or of
`:customer_id`.

# `list_meters`
*optional* 

```elixir
@callback list_meters(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:usage`. One page of meters; only those of `:status` (`:active`, `:inactive`) when given.

# `list_payment_links`
*optional* 

```elixir
@callback list_payment_links(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:payment_link`. One page of payment links, newest first; only `:active` ones when given.

# `list_payment_methods`
*optional* 

```elixir
@callback list_payment_methods(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:payment_method`. One page of a customer's saved payment methods (`:customer_id`).

# `list_payments`
*optional* 

```elixir
@callback list_payments(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:payment_list`. One page of payments, newest first; only `:customer_id`'s when given.

# `list_payouts`
*optional* 

```elixir
@callback list_payouts(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:payout`. One page of payouts, newest first; only those of `:status` when given.

# `list_portal_configurations`
*optional* 

```elixir
@callback list_portal_configurations(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:portal`. One page of portal setups, newest first; only `:active` ones, or the
`:default` one, when given.

# `list_prices`
*optional* 

```elixir
@callback list_prices(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:catalog`. One page of prices, newest first; only those of `:product_id`, with
`:lookup_key`, or `:active` when given.

# `list_products`
*optional* 

```elixir
@callback list_products(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:catalog`. One page of products, newest first; only `:active` ones when given.

# `list_promotion_codes`
*optional* 

```elixir
@callback list_promotion_codes(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:discount`. One page of promotion codes, newest first; only those with `:code`, of
`:coupon_id`, or `:active` when given.

# `list_refunds`
*optional* 

```elixir
@callback list_refunds(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:refund_read`. One page of refunds, newest first; `:payment_id` filters to one payment.

# `list_shipping_rates`
*optional* 

```elixir
@callback list_shipping_rates(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:shipping`. One page of shipping rates, newest first; only `:active` ones when given.

# `list_subscription_schedules`
*optional* 

```elixir
@callback list_subscription_schedules(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:subscription_schedule`. One page of schedules, newest first; only `:customer_id`'s, or
those not started yet (`scheduled: true`), when given.

# `list_subscriptions`
*optional* 

```elixir
@callback list_subscriptions(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:subscription_list`. One page of subscriptions, newest first; only those of
`:customer_id`, charging `:price_id`, or in `:status` (a `MishkaPay.Subscription` status, or
`:all`) when given.

# `list_tax_ids`
*optional* 

```elixir
@callback list_tax_ids(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:tax_id`. One page of the tax ids of customer `:customer_id`.

# `list_tax_rates`
*optional* 

```elixir
@callback list_tax_rates(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:tax_rate`. One page of tax rates, newest first; `:active` and `:inclusive` filter.

# `list_tax_registrations`
*optional* 

```elixir
@callback list_tax_registrations(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:tax_setup`. One page of the seller's tax registrations; `:status` is `:active` (the
default), `:scheduled`, `:expired` or `:all`.

# `list_transfers`
*optional* 

```elixir
@callback list_transfers(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:transfer`. One page of transfers, newest first; only those to `:destination` or of
`:transfer_group` when given.

# `login_link`
*optional* 

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

With `:connect`. Makes a one-time link into a connected account's own dashboard.

# `mark_invoice_uncollectible`
*optional* 

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

With `:invoice`. Marks an open bill as one that will not be paid.

# `offered?`
*optional* 

```elixir
@callback offered?() :: boolean()
```

Optional. `false` keeps an installed provider out of `offered/0`, for example while it has no keys anywhere.

# `pause_collection`
*optional* 

```elixir
@callback pause_collection(
  subscription_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

With `:subscription_change`. Pauses collecting a subscription's payments: `:behavior` says
what happens to its invoices meanwhile, `:resumes_at` when collection starts again by itself.

# `pay_invoice`
*optional* 

```elixir
@callback pay_invoice(
  invoice_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

With `:invoice`. Charges an open bill now, or marks it paid outside the provider (`out_of_band: true`).

# `portal_session`
*optional* 

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

With `:portal`. Opens the provider's billing page for a customer and answers its `:url`.

# `preview_credit_note`
*optional* 

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

With `:credit_note`. The note `create_credit_note/2` would make, without making it.

# `preview_subscription_change`
*optional* 

```elixir
@callback preview_subscription_change(
  MishkaPay.Subscription.Change.t(),
  MishkaPay.Credentials.t()
) :: {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

With `:subscription_change`. The invoice the change would make, with its proration lines,
without changing anything.

# `raw_request`
*optional* 

```elixir
@callback raw_request(MishkaPay.RawRequest.t(), MishkaPay.Credentials.t()) ::
  {:ok, map()} | {:error, Splode.Error.t()}
```

With `:raw_request`. Sends one call to `:path` of the provider's own API with the tenant's keys
and answers the provider's decoded answer as it is, or its error as a `MishkaPay.Errors` one.
An option of `:options` the provider cannot send is refused before any request.

# `reactivate_meter`
*optional* 

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

With `:usage`. Turns a meter that was off on again.

# `record_tax`
*optional* 

```elixir
@callback record_tax(
  calculation_id :: String.t(),
  reference :: String.t(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.TaxCalculation.Transaction.t()} | {:error, Splode.Error.t()}
```

With `:tax`. Records the sale of a calculation under the caller's `reference`, for the tax reports.

# `refund`
*optional* 

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

With `:refund`. Gives money back on a payment and answers the refund as the provider made it.

# `refund_application_fee`
*optional* 

```elixir
@callback refund_application_fee(
  fee_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.ApplicationFee.t()} | {:error, Splode.Error.t()}
```

With `:connect`. Gives an application fee back to the seller: all of it, or `:amount`;
`:reference` makes the idempotency key. Answers the fee after.

# `release_subscription_schedule`
*optional* 

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

With `:subscription_schedule`. Ends the schedule; its subscription goes on alone.

# `report_usage`
*optional* 

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

With `:usage`. Reports one use by a customer, once for each reference.

# `resume_collection`
*optional* 

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

With `:subscription_change`. Collects a paused subscription's payments again.

# `resume_subscription`
*optional* 

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

With `:subscription`. Takes back a cancel set for the period's end, so the subscription goes on,
and answers it as the provider has it after.

# `reverse_transfer`
*optional* 

```elixir
@callback reverse_transfer(
  transfer_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Transfer.t()} | {:error, Splode.Error.t()}
```

With `:transfer`. Takes a transfer back from the connected account: all of it, or `:amount`;
`:reference` makes the idempotency key. Answers the transfer after.

# `search_customers`
*optional* 

```elixir
@callback search_customers(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:customer`. One page of customers that match every filter given: `:email`, `:name`,
`:reference` (the host's own id kept on the customer); `:api`, at a provider with two customer
APIs, the one the answers are named by.

# `search_subscriptions`
*optional* 

```elixir
@callback search_subscriptions(opts :: keyword(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
```

With `:subscription_list`. One page of subscriptions that match every filter given:
`:status`, `:reference` (the caller's own id from the checkout), `:metadata` (pairs that must
all match).

# `send_invoice`
*optional* 

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

With `:invoice`. Emails an open bill to its customer.

# `set_default_payment_method`
*optional* 

```elixir
@callback set_default_payment_method(
  customer_id :: String.t(),
  payment_method_id :: String.t(),
  MishkaPay.Credentials.t()
) :: {:ok, MishkaPay.Customer.t()} | {:error, Splode.Error.t()}
```

With `:payment_method`. Makes a saved payment method the one a customer's invoices and
subscriptions charge, and answers the customer after (`:default_payment_method`).

# `upcoming_invoice`
*optional* 

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

With `:subscription`. The bill a subscription will make next, as the provider counts it now.

# `update_connected_account`
*optional* 

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

With `:connect`. Changes the details of connected account `:id` that are given.

# `update_customer`
*optional* 

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

With `:customer`. Changes the fields set on the customer whose `:id` it carries.

# `update_dispute`
*optional* 

```elixir
@callback update_dispute(MishkaPay.Dispute.Evidence.t(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Dispute.t()} | {:error, Splode.Error.t()}
```

With `:dispute`. Adds evidence to a dispute, and sends it with `:submit`.

# `update_invoice_item`
*optional* 

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

With `:invoice_item`. Changes the fields set on the item whose `:id` it carries.

# `update_meter`
*optional* 

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

With `:usage`. Renames the meter whose `:id` it carries; how it counts never changes.

# `update_payment_intent`
*optional* 

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

With `:intent`. Changes payment intent `:id` before it is paid: only the fields set.

# `update_payment_link`
*optional* 

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

With `:payment_link`. Changes the options set on a link (`:active` and the rest); its prices stay.

# `update_portal_configuration`
*optional* 

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

With `:portal`. Changes the fields set on the portal setup whose `:id` it carries.

# `update_price`
*optional* 

```elixir
@callback update_price(MishkaPay.Price.t(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.Price.t()} | {:error, Splode.Error.t()}
```

With `:catalog`. Changes whether a price is on sale (`:active`), and its metadata.

# `update_product`
*optional* 

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

With `:catalog`. Changes the fields set on the product whose `:id` it carries.

# `update_promotion_code`
*optional* 

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

With `:discount`. Turns a promotion code off or on again (`:active`), and its metadata.

# `update_subscription_schedule`
*optional* 

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

With `:subscription_schedule`. Changes what the schedule carries (`:phases`, `:end_behavior`,
`:metadata`) on the schedule whose `:id` it carries.

# `update_tax_rate`
*optional* 

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

With `:tax_rate`. Changes tax rate `:id`: only the fields set, never its percentage or whether it
is inclusive.

# `update_tax_settings`
*optional* 

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

With `:tax_setup`. Changes the site's tax settings: only the fields set.

# `upload_file`
*optional* 

```elixir
@callback upload_file(MishkaPay.File.Upload.t(), MishkaPay.Credentials.t()) ::
  {:ok, MishkaPay.File.t()} | {:error, Splode.Error.t()}
```

With `:file`. Uploads a file, after checking the provider takes its type and size.

# `usage_summary`
*optional* 

```elixir
@callback usage_summary(
  meter_id :: String.t(),
  opts :: keyword(),
  MishkaPay.Credentials.t()
) ::
  {:ok, MishkaPay.Usage.Summary.t()} | {:error, Splode.Error.t()}
```

With `:usage`. What a meter counted for `:customer_id` from `:from` to `:to` (both
`DateTime`, `:to` after `:from`).

# `verify_webhook`
*optional* 

```elixir
@callback verify_webhook(
  payload :: binary(),
  headers :: [{String.t(), String.t()}],
  MishkaPay.Credentials.t()
) :: {:ok, MishkaPay.Event.t()} | {:error, Splode.Error.t()}
```

With `:webhook`. Checks a provider's signed message (the raw body and headers as they came) with
the tenant's webhook secret and answers it as a `MishkaPay.Event`, or a
`MishkaPay.Errors.BadSignature` error.

# `void_credit_note`
*optional* 

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

With `:credit_note`. Voids an issued credit note, and answers it after.

# `void_invoice`
*optional* 

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

With `:invoice`. Ends an open bill that should never have been sent.

# `all`

```elixir
@spec all() :: [module()]
```

Every installed provider, the first of each id. None when the event cannot run.

# `capabilities`

```elixir
@spec capabilities() :: [capability()]
```

Every capability a provider may declare.

# `capable`

```elixir
@spec capable(String.t(), capability()) ::
  {:ok, module()} | {:error, Splode.Error.t()}
```

The offered provider `id` when it has `capability`, or an `UnknownProvider` or `Unsupported`
error.

# `fetch`

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

The offered provider whose id is `id`.

# `label_of`

```elixir
@spec label_of(String.t() | nil) :: String.t()
```

The name a person reads for provider `id`: its `label/0` when it is installed (`"Stripe"`,
`"PayPal"`), else the id with a capital.

# `offered`

```elixir
@spec offered() :: [module()]
```

The installed providers this installation offers: every one, unless its `offered?/0` says not.

# `operations`

```elixir
@spec operations(capability()) :: keyword(pos_integer())
```

Lists what a capability asks a provider to define, such as `[checkout: 2, fetch_payment: 2]`.

---

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