How Mishka Pay works

v0.0.1

Mishka Pay is an Elixir and Ash payment SDK built from a few small ideas: a provider is a plugin, keys are answered at runtime for each site, every call returns a plain struct or a typed error, and the provider, not your database, is the source of truth. This page explains those ideas and why they exist, so the other pages make sense. It describes version 0.0.1. Mishka Pay is built so that one install can serve many sites that each take their own payments, as Mishka CMS does, and it works in any Phoenix or plain Elixir project.

What Mishka Pay is for

Every payment provider has its own words for the same few things: a hosted page where a buyer pays, a payment, a refund, a subscription, a signed message that says something changed. Mishka Pay gives those things one shape. You call MishkaPay.checkout/1 and get a checkout, whether the provider is Stripe or PayPal. Stripe is the full provider, with subscriptions, invoices, tax, usage billing and Connect. PayPal has a smaller adapter.

The same design makes it possible to serve many sites. A call names its tenant, which is a site, and the keys for that site are looked up as the call runs.

Providers are plugins

A provider is a module that implements MishkaPay.Provider and runs as a plugin of Mishka Installer on the mishka_pay:providers event. You supervise it like any child. The registry is the only list of installed providers, and nothing is cached. Every call names the provider by its id, such as "stripe", and nothing else names a provider.

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

A project can add its own provider without changing Mishka Pay. Mishka Pay's application starts Stripe and PayPal for you. Choose a subset with config :mishka_pay, providers: [MishkaPay.Providers.Stripe]. If you write a provider, the test kit has a contract test every provider must pass.

Capabilities and Unsupported

A provider lists its capabilities, such as :checkout, :refund, :subscription or :tax. Each capability brings the functions it needs, and a provider that declares one without them does not compile. A call to something the provider does not list answers MishkaPay.Errors.Unsupported before any request leaves your server. The same goes for an option the provider cannot send: it is refused, never dropped. Capabilities by provider has the table.

Keys are answered at runtime, per site

Mishka Pay never reads keys from config.exs. A keys plugin on the mishka_pay:credentials event answers them for each provider and tenant, from your settings, your database or the environment. A project with one site answers the same keys for every tenant. A multi-site project reads the site's own, so changing a site's keys applies to the next call with no restart.

Besides the keys, the same answer carries the settings that belong to a site, such as whether refunds can happen once or many times, whether Stripe Tax counts tax, and which Stripe API version family to use for customers. Keys and options lists them all. Keys never reach a log line or a telemetry event.

Calls answer structs or errors

Every call returns {:ok, struct} or {:error, error}. The structs (MishkaPay.Payment, MishkaPay.Subscription, MishkaPay.Refund and the rest) are built with GuardedStruct, so input is checked before a request and the same field means the same thing for every provider. Money is a string amount and a currency, checked against the currency's own decimals. The errors are MishkaPay.Errors exceptions with a class you can match. See Errors and telemetry.

A write is safe to retry. A call that carries a reference makes its idempotency key from it, so the same reference never makes two checkouts, refunds or transfers. Without one, a write gets a fresh key that its own retries reuse. A network error and the answers 408, 429, 500, 502, 503 and 504 are tried again, and a write only when the provider takes an idempotency key.

The provider is the source of truth

A success URL says the buyer came back. A webhook body says what the provider chose to send. Neither is proof. Read the payment or subscription again with fetch_payment/3 or fetch_subscription/3 before you give access, and give access from the status. With the Ash layer, rows are written from what the provider answers and are read again when a webhook says something changed. Two syncs of one object can run at once, and the row keeps the newer read.

Changes are events

Mishka Pay announces what happens as events of Mishka Installer, and every extension point is one of them. Plugins listen to them like any other plugin.

EventWhen
mishka_pay:providersCollects the installed providers.
mishka_pay:credentialsA keys plugin answers keys and settings for a provider and tenant.
mishka_pay:checkout:beforeA gate that can refuse a checkout. A refusal is Errors.Refused.
mishka_pay:webhook:receivedA verified webhook arrived.
mishka_pay:event:processThe Ash inbox is working an event.
mishka_pay:payment:changed, subscription, customer, disputeThe Ash layer wrote a row.

The names are in MishkaPay.Events. A listener answers its state, so return {:reply, state} even when it does nothing. MishkaPay.PubSub turns the changes into Phoenix PubSub broadcasts with one line. See Keep payments in Ash resources and Mishka CMS.

Newest API by default

Mishka Pay uses the newest Stripe APIs unless you choose the older ones. Customers are Accounts v2 accounts, connected accounts use Accounts v2, webhooks use thin events sent to an event destination, and new subscriptions use the flexible billing mode. Each has an older choice that you set per site in the keys, or per call: customer_api: :v1, connect_api: :v1, events: :snapshot, webhook_api: :v1 and billing_mode: :classic. A customer or connected account made with one setting keeps working after you change it, because every read and change uses the API the id belongs to, and the webhook takes both kinds of event whatever the setting. The Stripe API version Mishka Pay sends is pinned. mix mishka_pay.stripe.check_version fails when Stripe has published a newer one.