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]
endSupervise 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, fromcapability/0. A call to something not listed answers aMishkaPay.Errors.Unsupportederror 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/2andfetch_payment/2;:embedded_checkout: nothing more;checkout/2also takesui_mode: :embedded;:capture:capture_payment/3,cancel_payment/2(checkout/2also takescapture: :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/2andupcoming_invoice/2(a subscription starts with a checkout inmode: :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_countriesand: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 inmode: :setupsaves one);:discount: coupons and promotion codes (create_coupon/2and the rest);:catalog: products and prices (create_product/2and 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,:destinationand: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.
Summary
Types
What a provider can do
Callbacks
With :dispute. Accepts the loss: the dispute closes as lost.
With :connect. Makes a one-time onboarding or update link for a connected account.
With :customer_balance. Changes a customer's balance: below zero gives credit.
With :fraud. Lets an open review's payment through, and answers the review closed.
With :entitlement. Attaches a feature to a catalog product, and answers the feature.
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.
With :capture. Lets the money held on an :authorized payment go; it ends :canceled.
With :intent. Cancels a payment intent that is not paid, or lets a held one go.
With :payout. Stops a payout that is still pending; its money stays in the balance.
With :intent. Cancels a setup intent that has not succeeded.
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.
With :subscription_schedule. Ends the schedule and its subscription now; :invoice_now bills
what is left, :prorate credits time not used.
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.
What the provider can do. Set by use.
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.
With :subscription_change. Changes a subscription's plan or quantity as the change says,
bills the difference its way, and answers the subscription after.
Optional. Whether the provider takes keys, with one read call that changes nothing
(MishkaPay.Check).
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.
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.
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.
With :intent. Confirms a setup intent on the server, as confirm_payment_intent/3.
With :connect. Makes a connected account for a seller; its :reference makes the
idempotency key.
With :discount. Makes a coupon and answers it with its :id.
With :credit_note. Makes a credit note on :invoice_id for :amount or :lines, and
answers it with its :id.
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.
With :entitlement. Makes a feature a product can give.
With :invoice. Makes a draft bill with its items, and answers it.
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.
With :usage. Makes a meter that counts usage reported under its event name.
With :intent. Makes a payment intent for the site's own card form, and answers it with its
:id and :client_secret.
With :payment_link. Makes a payment link and answers it with its :id and :url.
With :portal. Makes a portal setup and answers it with its :id.
With :catalog. Makes a price of a product (:product_id) and answers it with its :id.
With :catalog. Makes a product and answers it with its :id.
With :discount. Makes a promotion code for a coupon and answers it with its :id.
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.
With :shipping. Makes a shipping rate and answers it with its :id.
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.
With :tax_id. Adds a tax id to the customer it names (:customer_id), and answers it.
With :tax_rate. Makes a tax rate, and answers it with its :id.
With :tax_setup. Registers the seller to collect tax in a country, and answers it.
With :transfer. Sends money to a connected account; its :reference makes it once.
With :usage. Turns a meter off: it takes no more usage and no new price.
With :discount. Removes a coupon so it can no longer be applied.
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.
With :invoice. Deletes a draft bill.
With :invoice_item. Removes an item that is not on a finalized bill.
With :tax_id. Removes one tax id from a customer.
With :payment_method. Takes a payment method off its customer for good, and answers it
after, with no :customer_id.
With :expire. Ends an open checkout so it can no longer be paid, and answers it after.
With :tax_setup. Ends a tax registration at a time (nil: now), and answers it.
With :connect. Reads one application fee, the platform's cut of a seller's sale.
With :balance. The seller's balance, available and pending, in each currency.
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.
With :connect. Reads one connected account; opts may name the :api to read it with.
With :discount. Reads one coupon again.
With :credit_note. Reads one credit note again, with its lines.
With :customer. Reads one customer again, on the API its id belongs to.
With :dispute. Reads one dispute.
With :file. Reads one file the provider keeps.
With :fraud. Reads one review, open or closed.
With :fraud. Reads one early fraud warning.
With :subscription. Reads one invoice, with its lines.
With :usage. Reads one meter again.
With :checkout. Reads one payment again from the provider, its source of truth.
With :intent. Reads one payment intent, with its status.
With :payment_link. Reads one payment link again.
With :payment_method. Reads one saved payment method again.
With :payout. Reads one payout of the account the keys act for.
With :portal. Reads one portal setup.
With :catalog. Reads one price again.
With :catalog. Reads one product again.
With :discount. Reads one promotion code again.
With :refund_read. Reads one refund again, with its status.
With :intent. Reads one setup intent, with its status.
With :subscription. Reads one subscription again from the provider.
With :subscription_schedule. Reads one schedule again, with its phases.
With :tax_rate. Reads one tax rate, archived or not.
With :tax_setup. Reads the site's tax settings.
With :transfer. Reads one transfer.
With :file. Makes a public link to a file; :expires_at ends it.
With :invoice. Opens a draft for payment: it gets its number and can be paid.
The provider's id, such as "stripe". Set by use.
The name a person reads. Set by use.
With :connect. One page of application fees, newest first; only :charge_id's when given.
With :balance. One page of the balance's movements, newest first; only those a :payout_id
paid out, or of :type, when given.
With :connect. One page of the platform's connected accounts, newest first.
With :discount. One page of coupons, newest first.
With :credit_note. One page of a credit note's lines (MishkaPay.CreditNote.Lines).
With :credit_note. One page of credit notes, newest first; only those on :invoice_id or of
:customer_id when given.
With :customer_balance. One page of the changes to :customer_id's balance, newest first.
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.
With :dispute. One page of disputes, newest first; only :payment_id's when given.
With :entitlement. One page of the features :customer_id may use now.
With :event_list. One page of the provider's events, newest first: :since (a DateTime)
and :types (a list of event types) filter them.
With :fraud. One page of the reviews still open, newest first.
With :fraud. One page of early fraud warnings, newest first; only those about :payment_id
or :charge_id when given.
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.
With :subscription. One page of invoices, newest first: those of :subscription_id or of
:customer_id.
With :usage. One page of meters; only those of :status (:active, :inactive) when given.
With :payment_link. One page of payment links, newest first; only :active ones when given.
With :payment_method. One page of a customer's saved payment methods (:customer_id).
With :payment_list. One page of payments, newest first; only :customer_id's when given.
With :payout. One page of payouts, newest first; only those of :status when given.
With :portal. One page of portal setups, newest first; only :active ones, or the
:default one, when given.
With :catalog. One page of prices, newest first; only those of :product_id, with
:lookup_key, or :active when given.
With :catalog. One page of products, newest first; only :active ones when given.
With :discount. One page of promotion codes, newest first; only those with :code, of
:coupon_id, or :active when given.
With :refund_read. One page of refunds, newest first; :payment_id filters to one payment.
With :shipping. One page of shipping rates, newest first; only :active ones when given.
With :subscription_schedule. One page of schedules, newest first; only :customer_id's, or
those not started yet (scheduled: true), when given.
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.
With :tax_id. One page of the tax ids of customer :customer_id.
With :tax_rate. One page of tax rates, newest first; :active and :inclusive filter.
With :tax_setup. One page of the seller's tax registrations; :status is :active (the
default), :scheduled, :expired or :all.
With :transfer. One page of transfers, newest first; only those to :destination or of
:transfer_group when given.
With :connect. Makes a one-time link into a connected account's own dashboard.
With :invoice. Marks an open bill as one that will not be paid.
Optional. false keeps an installed provider out of offered/0, for example while it has no keys anywhere.
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.
With :invoice. Charges an open bill now, or marks it paid outside the provider (out_of_band: true).
With :portal. Opens the provider's billing page for a customer and answers its :url.
With :credit_note. The note create_credit_note/2 would make, without making it.
With :subscription_change. The invoice the change would make, with its proration lines,
without changing anything.
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.
With :usage. Turns a meter that was off on again.
With :tax. Records the sale of a calculation under the caller's reference, for the tax reports.
With :refund. Gives money back on a payment and answers the refund as the provider made it.
With :connect. Gives an application fee back to the seller: all of it, or :amount;
:reference makes the idempotency key. Answers the fee after.
With :subscription_schedule. Ends the schedule; its subscription goes on alone.
With :usage. Reports one use by a customer, once for each reference.
With :subscription_change. Collects a paused subscription's payments again.
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.
With :transfer. Takes a transfer back from the connected account: all of it, or :amount;
:reference makes the idempotency key. Answers the transfer after.
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.
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).
With :invoice. Emails an open bill to its customer.
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).
With :subscription. The bill a subscription will make next, as the provider counts it now.
With :connect. Changes the details of connected account :id that are given.
With :customer. Changes the fields set on the customer whose :id it carries.
With :dispute. Adds evidence to a dispute, and sends it with :submit.
With :invoice_item. Changes the fields set on the item whose :id it carries.
With :usage. Renames the meter whose :id it carries; how it counts never changes.
With :intent. Changes payment intent :id before it is paid: only the fields set.
With :payment_link. Changes the options set on a link (:active and the rest); its prices stay.
With :portal. Changes the fields set on the portal setup whose :id it carries.
With :catalog. Changes whether a price is on sale (:active), and its metadata.
With :catalog. Changes the fields set on the product whose :id it carries.
With :discount. Turns a promotion code off or on again (:active), and its metadata.
With :subscription_schedule. Changes what the schedule carries (:phases, :end_behavior,
:metadata) on the schedule whose :id it carries.
With :tax_rate. Changes tax rate :id: only the fields set, never its percentage or whether it
is inclusive.
With :tax_setup. Changes the site's tax settings: only the fields set.
With :file. Uploads a file, after checking the provider takes its type and size.
With :usage. What a meter counted for :customer_id from :from to :to (both
DateTime, :to after :from).
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.
With :credit_note. Voids an issued credit note, and answers it after.
With :invoice. Ends an open bill that should never have been sent.
Functions
Every installed provider, the first of each id. None when the event cannot run.
Every capability a provider may declare.
The offered provider id when it has capability, or an UnknownProvider or Unsupported
error.
The offered provider whose id is id.
The name a person reads for provider id: its label/0 when it is installed ("Stripe",
"PayPal"), else the id with a capital.
The installed providers this installation offers: every one, unless its offered?/0 says not.
Lists what a capability asks a provider to define, such as [checkout: 2, fetch_payment: 2].
Types
@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 inmode: :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.
Callbacks
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@callback capabilities() :: [capability()]
What the provider can do. Set by use.
@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.
@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.
@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).
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@callback delete_invoice(invoice_id :: String.t(), MishkaPay.Credentials.t()) :: :ok | {:error, Splode.Error.t()}
With :invoice. Deletes a draft bill.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@callback fetch_coupon(coupon_id :: String.t(), MishkaPay.Credentials.t()) :: {:ok, MishkaPay.Coupon.t()} | {:error, Splode.Error.t()}
With :discount. Reads one coupon again.
@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.
@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.
@callback fetch_dispute(dispute_id :: String.t(), MishkaPay.Credentials.t()) :: {:ok, MishkaPay.Dispute.t()} | {:error, Splode.Error.t()}
With :dispute. Reads one dispute.
@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.
@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.
@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.
@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.
@callback fetch_meter(meter_id :: String.t(), MishkaPay.Credentials.t()) :: {:ok, MishkaPay.Meter.t()} | {:error, Splode.Error.t()}
With :usage. Reads one meter again.
@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.
@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.
@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.
@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.
@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.
@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.
@callback fetch_price(price_id :: String.t(), MishkaPay.Credentials.t()) :: {:ok, MishkaPay.Price.t()} | {:error, Splode.Error.t()}
With :catalog. Reads one price again.
@callback fetch_product(product_id :: String.t(), MishkaPay.Credentials.t()) :: {:ok, MishkaPay.Product.t()} | {:error, Splode.Error.t()}
With :catalog. Reads one product again.
@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.
@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.
@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.
@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.
@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.
@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.
@callback fetch_tax_settings(MishkaPay.Credentials.t()) :: {:ok, MishkaPay.TaxSettings.t()} | {:error, Splode.Error.t()}
With :tax_setup. Reads the site's tax settings.
@callback fetch_transfer(transfer_id :: String.t(), MishkaPay.Credentials.t()) :: {:ok, MishkaPay.Transfer.t()} | {:error, Splode.Error.t()}
With :transfer. Reads one transfer.
@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.
@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.
@callback id() :: String.t()
The provider's id, such as "stripe". Set by use.
@callback label() :: String.t()
The name a person reads. Set by use.
@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.
@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.
@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.
@callback list_coupons(opts :: keyword(), MishkaPay.Credentials.t()) :: {:ok, MishkaPay.Page.t()} | {:error, Splode.Error.t()}
With :discount. One page of coupons, newest first.
@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).
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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).
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@callback offered?() :: boolean()
Optional. false keeps an installed provider out of offered/0, for example while it has no keys anywhere.
@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.
@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).
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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).
@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.
@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).
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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).
@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.
@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.
@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.
Functions
@spec all() :: [module()]
Every installed provider, the first of each id. None when the event cannot run.
@spec capabilities() :: [capability()]
Every capability a provider may declare.
@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.
@spec fetch(String.t()) :: {:ok, module()} | {:error, Splode.Error.t()}
The offered provider whose id is id.
The name a person reads for provider id: its label/0 when it is installed ("Stripe",
"PayPal"), else the id with a capital.
@spec offered() :: [module()]
The installed providers this installation offers: every one, unless its offered?/0 says not.
@spec operations(capability()) :: keyword(pos_integer())
Lists what a capability asks a provider to define, such as [checkout: 2, fetch_payment: 2].