MishkaPay (Mishka Pay v0.0.1)

Copy Markdown View Source

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.

Summary

Functions

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

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.

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.

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.

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

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

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

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.

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

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.

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

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

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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

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.

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.

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

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.

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.

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.

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.

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

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).

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

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

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

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.

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.

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.

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).

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.

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.

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.

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

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

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").

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

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

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

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.

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.

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.

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

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

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.

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).

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

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

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).

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

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

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

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

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

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

Reads payment intent payment_intent_id from provider, with its status.

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

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

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.

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

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

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

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

Reads refund refund_id from provider again, with its status.

Reads setup intent setup_intent_id from provider, with its status.

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

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

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

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

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

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.

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

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:.

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:.

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.

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

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

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:.

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

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.

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

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.

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.

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:.

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.

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:.

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:.

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

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

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.

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.

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:.

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:.

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:.

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

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:.

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

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

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:.

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.

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

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:.

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:.

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:.

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.

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

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.

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).

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.

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

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.

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

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.

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

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.

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

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.

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.

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.

Collects paused subscription subscription_id's payments again.

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

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.

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.

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.

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

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.

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

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.

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

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.

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.

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

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).

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.

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

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

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.

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.

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.

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.

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.

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

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).

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

Functions

accept_dispute(provider, dispute_id, tenant \\ nil)

@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(attrs)

@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(provider, customer_id, money, tenant \\ nil, opts \\ [])

@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(provider, review_id, tenant \\ nil)

@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(provider, price_id, tenant \\ nil)

@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(provider, product_id, tenant \\ nil)

@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(provider, product_id, feature_id, tenant \\ nil)

@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(attrs)

@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(provider, payment_id, tenant \\ nil)

@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(provider, payment_intent_id, tenant \\ nil)

@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(provider, payout_id, tenant \\ nil)

@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(provider, setup_intent_id, tenant \\ nil)

@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(provider, subscription_id, tenant \\ nil, opts \\ [])

@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(provider, schedule_id, tenant \\ nil, opts \\ [])

@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(attrs)

@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(provider, payment_id, tenant \\ nil, opts \\ [])

@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(attrs)

@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(attrs)

@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(provider, account_id, tenant \\ nil, opts \\ [])

@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(provider, payment_intent_id, tenant \\ nil, opts \\ [])

@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(provider, setup_intent_id, tenant \\ nil, opts \\ [])

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(provider, customer_id, attrs, tenant \\ nil)

@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(attrs)

@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(attrs)

@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(attrs)

@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(provider, meter_id, tenant \\ nil)

@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(provider, coupon_id, tenant \\ nil)

@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(provider, customer_id, tenant \\ nil)

@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(provider, invoice_id, tenant \\ nil)

@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(provider, invoice_item_id, tenant \\ nil)

@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(provider, customer_id, tax_id_id, tenant \\ nil)

@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(provider, payment_method_id, tenant \\ nil)

@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(provider, checkout_id, tenant \\ nil)

@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(provider, registration_id, tenant \\ nil, opts \\ [])

@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(provider, fee_id, tenant \\ nil)

@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(provider, tenant \\ nil)

@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(provider, checkout_id, tenant \\ nil)

@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(provider, account_id, tenant \\ nil, opts \\ [])

@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(provider, coupon_id, tenant \\ nil)

@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(provider, credit_note_id, tenant \\ nil)

@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(provider, customer_id, tenant \\ nil)

@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(provider, dispute_id, tenant \\ nil)

@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(provider, file_id, tenant \\ nil)

@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(provider, review_id, tenant \\ nil)

@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(provider, warning_id, tenant \\ nil)

@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(provider, invoice_id, tenant \\ nil)

@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(provider, meter_id, tenant \\ nil)

@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(provider, payment_id, tenant \\ nil)

@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(provider, payment_intent_id, tenant \\ nil)

@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(provider, payment_link_id, tenant \\ nil)

@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(provider, payment_method_id, tenant \\ nil)

@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(provider, payout_id, tenant \\ nil)

@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(provider, configuration_id, tenant \\ nil)

@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(provider, price_id, tenant \\ nil)

@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(provider, product_id, tenant \\ nil)

@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(provider, promotion_code_id, tenant \\ nil)

@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(provider, refund_id, tenant \\ nil)

@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(provider, setup_intent_id, tenant \\ nil)

@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(provider, subscription_id, tenant \\ nil)

@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(provider, schedule_id, tenant \\ nil)

@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(provider, tax_rate_id, tenant \\ nil)

@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(provider, tenant \\ nil)

@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(provider, transfer_id, tenant \\ nil)

@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(provider, file_id, tenant \\ nil, opts \\ [])

@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(provider, invoice_id, tenant \\ nil)

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, credit_note_id, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, customer_id, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, customer_id, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, customer_id, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts \\ [])

@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(provider, account_id, tenant \\ nil)

@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(provider, invoice_id, tenant \\ nil)

@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(provider, subscription_id, tenant \\ nil, opts \\ [])

@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(provider, invoice_id, tenant \\ nil, opts \\ [])

@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(attrs)

@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(attrs)

@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(attrs)

@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(provider, meter_id, tenant \\ nil)

@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(provider, calculation_id, reference, tenant \\ nil)

@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(attrs)

@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(provider, fee_id, tenant \\ nil, opts \\ [])

@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(provider, schedule_id, tenant \\ nil)

@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(provider, tenant \\ nil, opts)

@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(attrs)

@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(attrs)

@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(provider, subscription_id, tenant \\ nil)

@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(provider, subscription_id, tenant \\ nil)

@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(provider, transfer_id, tenant \\ nil, opts \\ [])

@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(provider, tenant \\ nil, opts)

@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(provider, tenant \\ nil, opts)

@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(provider, invoice_id, tenant \\ nil)

@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(provider, customer_id, payment_method_id, tenant \\ nil)

@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(provider, subscription_id, tenant \\ nil)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(attrs)

@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(provider, meter_id, customer_id, from, to, tenant \\ nil)

@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 (DateTimes, to not included), as one MishkaPay.Usage.Summary. A use reported a moment ago may not be counted yet.

void_credit_note(provider, credit_note_id, tenant \\ nil)

@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(provider, invoice_id, tenant \\ nil)

@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.