Stripe as a provider: one time payments with Stripe Checkout, reading a payment and refunds.
Supervise it to install it, and answer its keys for each tenant (MishkaPay.Credentials); only
secret_key is needed here, webhook_secret joins with webhooks.
children = [MishkaPay.Providers.Stripe]It talks to Stripe through MishkaPay.Client (retries, one idempotency key per call,
telemetry), with the tenant's secret key and one pinned Stripe API version,
2026-10-28.endive, so a change of the account's default version never changes what this
module reads. No third party Stripe library is used. Stripe's field names live only in
MishkaPay.Providers.Stripe.Mapper.
checkout/2opens a Checkout Session inpaymentmode and answers its page. A price's:tax_codeis its product tax code, and:merchant_of_record(the checkout's, else the tenant's setting inMishkaPay.Credentials) turns Stripe Managed Payments on or off for the session; an account with Managed Payments on by default needs a tax code on every price. The caller's:referencegoes to Stripe asclient_reference_idand as metadata on the session and its payment, and it makes the idempotency key, so the same reference never opens two sessions.fetch_checkout/2reads a Checkout Session back, with the PaymentIntent it made.capture: :automatic, on a checkout or a PaymentIntent, is Stripe'sautomatic_async(its default and recommended way),:automatic_syncits olderautomatic;:manualholds the money. Bothautomaticandautomatic_asyncread back as:automatic.fetch_payment/2reads a PaymentIntent with its latest charge, the charge's refunds and the customer, in one request: the buyer, the card, the receipt, why it failed and every refund.fetch_subscription/2,cancel_subscription/3,resume_subscription/2andlist_invoices/2read a Subscription with its customer and products, cancel it at once (DELETE) or at the period's end (cancel_at_period_end), take that back, and list its Invoices. A checkout inmode: :subscriptionstarts one, with its trial and the reference on the subscription.list_subscriptions/2lists them by customer, price or status (Stripe leaves canceled ones out unless asked for them or for:all), andsearch_subscriptions/2finds them with Stripe's search by status, reference or metadata. Every subscription it makes (a subscription checkout, a new schedule) sends Stripe'sbilling_mode:flexiblewithitemizedproration discounts, Stripe's recommended ones, unless the checkout, the schedule or the tenant's keys ask forclassicorincluded.create_subscription_schedule/2,fetch_subscription_schedule/2,list_subscription_schedules/2,update_subscription_schedule/2,release_subscription_schedule/2andcancel_subscription_schedule/3use Subscription Schedules (sub_sched_...): madefrom_subscription, or for a customer with phases; a phase's:iterationsand:intervalare itsduration(this API version has noiterations), and the reference makes the idempotency key and is kept in its metadata (set in a second request on one made from a subscription, which Stripe makes without metadata).create_customer/2,fetch_customer/2,update_customer/2,list_customers/2anddelete_customer/2keep customers with Accounts v2 (an account with the customer configuration,acct_..., the default) or as Customers (/v1/customers,cus_...), as the customer's:apior the tenant's:customer_apisays; a read, a change and a delete use the API the id belongs to. On v2 the email iscontact_email, the namedisplay_name, the phone and address the identity's individual's, the invoice default the customer configuration's billing; a read includes the configuration and the identity. The reference is kept in the metadata either way. A v2 delete closes the account (every configuration it has, read first); a v1 delete is for good and cancels the customer's subscriptions at once. A v2 list has no email filter and holds at most 20;search_customers/2is Stripe's Customer search on either, which finds customers made on v2 by the Customer Stripe links to each, and names them by their account on v2. Every call that names a customer sends anacct_id ascustomer_accountand acus_one ascustomer(checkout, intents, subscriptions and schedules, invoices, invoice items, credit notes, the portal, payments and promotion codes), and a path under/v1/customers/:idtakes either (tax ids, payment methods, the customer balance). Usage reports and summaries, entitlements and tax calculations take only acus_id: Stripe takes nocustomer_accountthere yet. Managed Payments sells to no customer account, so a checkout for one as the merchant of record is refused.create_tax_id/2,list_tax_ids/2anddelete_tax_id/3keep a customer's tax ids (txi_...);portal_session/2opens a billing portal session for one, with the portal configuration (bpc_...) it names;create_portal_configuration/2,update_portal_configuration/2,fetch_portal_configuration/2andlist_portal_configurations/2keep those (Stripe never deletes one:active: falseturns it off). Stripe answers a portal session only once the account's portal is set up (Settings, Billing, Customer portal), in test mode too.A checkout in
mode: :setupopens a session in Stripe'ssetupmode that saves a card without a charge, with Managed Payments off (Stripe takes no setup mode with it) and, without a known customer,customer_creation: always.list_payment_methods/2,fetch_payment_method/2,detach_payment_method/2andset_default_payment_method/3keep a customer's PaymentMethods (pm_...); the default is a change of the customer: a v1 Customer'sinvoice_settings.default_payment_method, or a v2 account'sconfiguration.customer.billing.default_payment_method.create_shipping_rate/2andlist_shipping_rates/2keep Shipping Rates (shr_...). A checkout's:shipping_countriesisshipping_address_collectionand its:shipping_ratesareshipping_options(a rate by id, orshipping_rate_data), up to 5, in payment mode only. Stripe refuses shipping where Managed Payments is on.calculate_tax/2asks Stripe Tax for the tax on a sale made outside Checkout (POST /v1/tax/calculations), andrecord_tax/3records it as a Tax Transaction (create_from_calculation) under the caller's reference, which makes its idempotency key. An account without Stripe Tax turned on is refused with code"tax_not_set_up".create_payment_intent/2,fetch_payment_intent/2,update_payment_intent/2,confirm_payment_intent/3andcancel_payment_intent/2keep PaymentIntents (pi_...) for a page with Stripe Elements;create_setup_intent/2,fetch_setup_intent/2,confirm_setup_intent/3andcancel_setup_intent/2keep SetupIntents (seti_...). The reference makes the idempotency key and is kept in the metadata, sofetch_payment/2reads a paid one with its reference like a checkout's.create_tax_rate/2,fetch_tax_rate/2,update_tax_rate/2andlist_tax_rates/2keep Tax Rates (txr_...) set by hand; a rate's reference makes the idempotency key and is kept in its metadata. A checkout's line takes them astax_rates, an invoice item too, and a draft invoice asdefault_tax_rates; Stripe takes none on a price or a payment link, nor with automatic tax on the same checkout.create_tax_registration/2,list_tax_registrations/2andexpire_tax_registration/3keep Stripe Tax Registrations (taxreg_...), the type and state sent under the country's owncountry_options;fetch_tax_settings/1andupdate_tax_settings/2read and change Stripe Tax's settings (head office, default tax code and behavior).create_invoice_item/2,update_invoice_item/2,delete_invoice_item/2andlist_invoice_items/2keep Invoice Items (ii_...) on their own: a charge that waits for the customer's next invoice, or goes on a draft one; the reference makes the idempotency key and is kept in the item's metadata.create_credit_note/2,preview_credit_note/2,fetch_credit_note/2,void_credit_note/2,list_credit_notes/2andlist_credit_note_lines/3use Credit Notes (cn_...) on finalized invoices: byamountor by line (an invoice lineil_...or a custom one), withrefund_amount,credit_amountandout_of_band_amount; the reference makes the idempotency key and is kept in the note's metadata. A note's lines carry no currency, so its lines are read with the note first.refund/2refunds a PaymentIntent, in full or in part, once or many times as the tenant allows (MishkaPay.Refund).upload_file/2sends a file tofiles.stripe.comasmultipart/form-data; dispute evidence only as PDF, JPEG or PNG, up to 5 MB, and its bytes must be the type it names.fetch_file/2reads one, andfile_link/3makes aMishkaPay.File.Link, a public address of it.update_dispute/2takes only a file id (file_...) in the evidence fields that hold a file, such asreceiptanduncategorized_file.create_meter/2,fetch_meter/2,update_meter/2(its display name only),list_meters/2,deactivate_meter/2,reactivate_meter/2,report_usage/2,cancel_usage/2andusage_summary/3use Billing Meters (mtr_...) and meter events, Stripe's basic usage billing; a price with:meter_idis a metered price on one. A report's reference makes itsidentifier; Stripe takes reports from the last 35 days and up to 5 minutes ahead, and counts summaries from and to whole minutes. A cancel is a meter event adjustment (type: cancel) of one identifier, within 24 hours of the report; the identifier makes its idempotency key. A report withstream: truegoes through the API v2 meter event stream instead: a meter event session's token, kept inMishkaPay.Helpers.TokenCacheuntil shortly before it runs out, then the report as JSON tometer-events.stripe.com, which Stripe checks after it answers.create_feature/2,attach_feature/3andlist_entitlements/2use Entitlements: features (feat_...) on products, and the active entitlements of a customer.fetch_fraud_warning/2andlist_fraud_warnings/2read Radar's early fraud warnings (issfr_...), by PaymentIntent or charge;list_fraud_reviews/2lists the open Reviews (prv_...) Radar's rules placed,fetch_fraud_review/2reads one andapprove_fraud_review/2approves it. Stripe sendsradar.early_fraud_warning.*andreview.opened/review.closedabout them.fetch_balance/1reads the payments balance, andlist_balance_transactions/2its balance transactions (txn_...), by payout (po_...) or type.adjust_customer_balance/2andlist_customer_balance/2keep a customer's credit balance (cbtxn_...): below zero is credit.create_connected_account/2,fetch_connected_account/3,update_connected_account/2,list_connected_accounts/2andclose_connected_account/3keep Connect accounts (acct_...) with Accounts v2 (/v2/core/accounts, the default) or Accounts v1 (/v1/accounts), as the call's:apior the tenant's:connect_apisays; both answer the sameMishkaPay.ConnectedAccount. On v2 an account is made with its configurations (a merchant asks for card payments, a recipient for transfers into its balance), its dashboard and who collects fees and losses, and read with its configurations, requirements, defaults and identity (include); on v1 the same choices are itscontrollerand capabilities. Its reference makes the idempotency key and is kept in its metadata. A v2 close sends every configuration the account has, read first; a v1 close is a reject.account_link/2makes anaccount_onboardingoraccount_updatelink (/v2/core/account_linksor/v1/account_links), andlogin_link/2an Express dashboard login link, on v1 only (v2 has none; it takes an account made with either). Stripe sendsaccount.updatedandaccount.application.deauthorizedas snapshot events, and API v2'sv2.core.account.*as thin events (thin_events/0). A platform that has not signed up for Connect is refused with code"connect_not_set_up", and an account made on v1 where Stripe allows only v2 with"connect_v1_refused".A checkout's
:application_fee,:destinationand:on_behalf_ofgo in itspayment_intent_data(application_fee_amount,transfer_data[destination],on_behalf_of), and:application_fee_percentwith them insubscription_data; ids areacct_...and the fee is in the items' currency.fetch_application_fee/2,list_application_fees/2andrefund_application_fee/3keep the fees (fee_...); a refund answers its fee expanded, in one request.create_transfer/2,fetch_transfer/2,list_transfers/2andreverse_transfer/3use Transfers (tr_...): the reference makes the idempotency key and is kept in metadata, and a reversal answers its transfer expanded.fetch_payout/2,list_payouts/2andcancel_payout/2read and stop Payouts (po_...) of the account the keys act for. Stripe sendstransfer.*,payout.*andapplication_fee.*about them.raw_request/2calls any path ofapi.stripe.comwith the tenant's key, the pinned version or the call's ownapi_version(Stripe-Version) and itsexpand[], and answers Stripe's JSON as it is; a write's reference, with its method and path, makes the idempotency key. A/v2/path is sent as API v2 takes it: a write's params as JSON, a read's as a query with indexed lists; v2 has noexpand[]and reads more withincludein the params.verify_webhook/3checks theStripe-Signatureheader: an HMAC-SHA256 of"<timestamp>.<raw body>"with the tenant'swebhook_secret, or any of itswebhook_secretswhile a rolled secret runs out, compared in constant time with everyv1signature in it, signed within the last five minutes (config :mishka_pay, MishkaPay.Providers.Stripe, webhook_tolerance: seconds), and from the same mode (live or test) as the tenant's keys. It takes snapshot and thin events alike; a thin one becomes the Event its snapshot event gives (thin_events/0), reading its object when an id it needs sits inside it.list_events/2reads the tenant's kind of events (:events, a call'sevents:first): thin ones from API v2's/v2/core/events, snapshot ones from/v1/events.MishkaPay.Providers.Stripe.WebhookEndpointsets up the endpoint for either kind.
A tenant whose keys name a connected account (:account_id, acct_...) acts as that account:
every request carries it in the Stripe-Account header (Stripe-Context on an API v2 path),
and only from the keys. Such a tenant
takes only webhook messages about its own account (Stripe's account on the event); one about
the platform or another connected account is refused like a bad signature. Keys without one
are the platform's own, and take its connected accounts' events, each with its :account.
Stripe answers 402 for a declined card (MishkaPay.Errors.Declined, with Stripe's decline code)
and other errors as MishkaPay.Errors.Rejected with its code and status. Both keep Stripe's
Request-Id header as :request_id (req_...) and its error page as :doc_url, for support and
the log; their messages never show them.
Stripe counts a few currencies differently from ISO 4217: ISK and UGX as two-decimal amounts
ending in 00, and MGA as zero-decimal. Mishka Pay sends and reads them as Stripe counts them,
and refuses a fraction of one before any request. HUF and TWD charge with two decimals like
other currencies (Stripe pays them out in whole units). It takes BHD, JOD, KWD, OMR and TND only with a last decimal of 0, and metadata up to 48 keys of 40
characters with values of 500; anything past that is an :invalid error before any request.
A refund first reads the payment. A tenant that refunds once is refused a second refund, and a part refund in another currency than the payment's, or over what is left, is refused, since Stripe counts a refund in the payment's own currency.
config :mishka_pay, MishkaPay.Providers.Stripe, base_url: "http://localhost:12111" points it at
another address, such as Stripe's own mock server in tests. Uploads go to files_url when it is
set, else to base_url when that is set, else to https://files.stripe.com; streamed usage
reports (stream: true) to meter_events_url the same way, else to
https://meter-events.stripe.com.
Summary
Functions
Returns a specification to start this module under a supervisor.
Callback implementation for MishkaInstaller.Event.Hook.enable/0.
The events Mishka Pay acts on, by the type their MishkaPay.Event carries: handled_events/0,
and thin_events/0 named as Mapper.event_type/1 names them (invoice.overpaid,
v2.core.account.updated). MishkaPay.replay_events/3 delivers only these.
Stripe's form encoding of nested params: %{"line_items" => [%{"quantity" => 1}]} becomes
[{"line_items[0][quantity]", "1"}]. nil values are left out.
Callback implementation for MishkaInstaller.Event.Hook.get/0.
The Stripe events that change what Mishka Pay keeps, each with what it updates: :payment
(a resource with mishka_pay do kind :payment end), :subscription, :customer, :dispute,
:invoice, :product, :price, :coupon, :promotion_code or :payment_link; or the
provider object it is about (:credit_note, :tax_rate; :subscription_schedule, which names its
subscription too; :fraud_warning and :fraud_review, which name their payment too;
:account, a connected account, which the event names as its :account; :transfer,
:payout and :application_fee, money between accounts). Each is mapped to its
ids (MishkaPay.Event) and tested; any other event is still verified and stored, and changes
nothing. Send these to the webhook endpoint in the Stripe Dashboard.
Optional. See MishkaInstaller.Event.Hook.health_check/0. Override to report health.
The API version of Stripe's newest published OpenAPI spec (github.com/stripe/openapi): its
info.version, the first value in Stripe's version form (2026-10-28.endive) in the file's
first bytes. mix mishka_pay.stripe.check_version compares it with version/0.
Optional. See MishkaInstaller.Event.Hook.on_dependency_error/1. Override to react.
The place of supply schemes Stripe takes for a tax registration of type in country (two
capital letters), from its API's country_options: a "standard" registration in an EU
country takes :standard, :small_seller or :inbound_goods; one in the other countries
whose standard registration has a scheme (the UK, Norway, Switzerland, Australia, Japan and
others) takes :standard or :inbound_goods; any other registration takes none ([]).
MishkaPay.create_tax_registration/1 refuses any other before asking Stripe.
Callback implementation for MishkaInstaller.Event.Hook.register/0.
Callback implementation for MishkaInstaller.Event.Hook.restart/0.
Stripe's signature of payload at timestamp (Unix seconds) with webhook secret: the v1
value of a Stripe-Signature header. verify_webhook/3 compares with it, and a test signs a
message with it.
Callback implementation for MishkaInstaller.Event.Hook.start/0.
Callback implementation for MishkaInstaller.Event.Hook.stop/0.
The thin events Mishka Pay maps, each with what it updates (the words of handled_events/0),
as an event destination with the thin payload sends them (the default of
MishkaPay.Providers.Stripe.WebhookEndpoint); Stripe never sends one to a
/v1/webhook_endpoints endpoint
Callback implementation for MishkaInstaller.Event.Hook.unregister/0.
The Stripe API version every request is pinned to.
Types
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec config() :: keyword()
@spec enable() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.enable/0.
The events Mishka Pay acts on, by the type their MishkaPay.Event carries: handled_events/0,
and thin_events/0 named as Mapper.event_type/1 names them (invoice.overpaid,
v2.core.account.updated). MishkaPay.replay_events/3 delivers only these.
Stripe's form encoding of nested params: %{"line_items" => [%{"quantity" => 1}]} becomes
[{"line_items[0][quantity]", "1"}]. nil values are left out.
@spec get() :: keyword()
Callback implementation for MishkaInstaller.Event.Hook.get/0.
The Stripe events that change what Mishka Pay keeps, each with what it updates: :payment
(a resource with mishka_pay do kind :payment end), :subscription, :customer, :dispute,
:invoice, :product, :price, :coupon, :promotion_code or :payment_link; or the
provider object it is about (:credit_note, :tax_rate; :subscription_schedule, which names its
subscription too; :fraud_warning and :fraud_review, which name their payment too;
:account, a connected account, which the event names as its :account; :transfer,
:payout and :application_fee, money between accounts). Each is mapped to its
ids (MishkaPay.Event) and tested; any other event is still verified and stored, and changes
nothing. Send these to the webhook endpoint in the Stripe Dashboard.
Optional. See MishkaInstaller.Event.Hook.health_check/0. Override to report health.
@spec latest_version() :: {:ok, String.t()} | {:error, Splode.Error.t()}
The API version of Stripe's newest published OpenAPI spec (github.com/stripe/openapi): its
info.version, the first value in Stripe's version form (2026-10-28.endive) in the file's
first bytes. mix mishka_pay.stripe.check_version compares it with version/0.
Optional. See MishkaInstaller.Event.Hook.on_dependency_error/1. Override to react.
@spec place_of_supply_schemes(String.t(), String.t()) :: [ :inbound_goods | :small_seller | :standard ]
The place of supply schemes Stripe takes for a tax registration of type in country (two
capital letters), from its API's country_options: a "standard" registration in an EU
country takes :standard, :small_seller or :inbound_goods; one in the other countries
whose standard registration has a scheme (the UK, Norway, Switzerland, Australia, Japan and
others) takes :standard or :inbound_goods; any other registration takes none ([]).
MishkaPay.create_tax_registration/1 refuses any other before asking Stripe.
@spec register() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.register/0.
@spec restart() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.restart/0.
Stripe's signature of payload at timestamp (Unix seconds) with webhook secret: the v1
value of a Stripe-Signature header. verify_webhook/3 compares with it, and a test signs a
message with it.
@spec start() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.start/0.
@spec stop() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.stop/0.
The thin events Mishka Pay maps, each with what it updates (the words of handled_events/0),
as an event destination with the thin payload sends them (the default of
MishkaPay.Providers.Stripe.WebhookEndpoint); Stripe never sends one to a
/v1/webhook_endpoints endpoint:
v1.<type>for each ofhandled_events/0, the thin form of the same event;- thin events with no snapshot event of their name, about what Mishka Pay keeps: a
subscription that turned
active,past_due,unpaid,trialingorincomplete, or whose items, cancel date or payment method changed; an invoice paid, due, overpaid, or whose lines or discounts changed; a schedule's phases; a product's or a price's activation, tax code, lookup key or default price; a promotion code used up; an entitlement added or removed; v1.billing.meter.error_report_triggeredandv1.billing.meter.no_meter_found(:meter): usage reports Stripe refused after answering (a streamed report). The event's:object_idis the meter (mtr_...) when Stripe found one; the counts and samples are in the full event,GET /v2/core/events/:id(MishkaPay.request/1);- API v2's connected account events (
v2.core.account.*,:account)::object_idand:accountare the account (read it withMishkaPay.fetch_connected_account/4). The events a customer made on Accounts v2 sends (v2.core.account.updatedand.closed,[identity].updated,[configuration.customer].*) name the account as its:customer_idtoo, so the Ash customer listener syncs it; for an account that is only a seller, that read answersresource_missingand the listener leaves the event done.
A thin event names its object and no more. verify_webhook/3 turns one into the same
MishkaPay.Event a snapshot event gives: an id that sits inside the object (the payment of a
charge, the subscription of an invoice, the customer of a tax id, the account a customer made
on Accounts v2 is) is read from the object, one request as the event's account; an event
whose object is itself the id it names (a PaymentIntent, a subscription, a product) needs none. Its :type is the snapshot
event's (invoice.paid for v1.invoice.paid, invoice.overpaid for the thin-only
v1.invoice.overpaid: Mapper.event_type/1), so a listener matches one name in either mode;
API v2's own events keep Stripe's names (v2.core.account.updated).
@spec unregister() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.unregister/0.
@spec version() :: String.t()
The Stripe API version every request is pinned to.