📖 What is Mishka Pay?
Mishka Pay is a payment SDK for Elixir and Phoenix. Checkouts, payments, refunds, subscriptions,
customers and verified webhooks get one shape, whatever the provider. You call
MishkaPay.checkout/1 and get a checkout, from Stripe or from PayPal.
It is built so one install can serve many sites, each taking its own payments, as Mishka CMS does. It works the same in any Phoenix or plain Elixir project.
✨ Why Mishka Pay
- 🔌 Providers are plugins:
a provider is a module that implements
MishkaPay.Provider. Add your own bank or payment gateway as a plugin, with no fork of Mishka Pay. A contract test (MishkaPay.ProviderCase) checks it. The plugin system underneath is Mishka Installer. - 💳 Stripe in full, PayPal included: Stripe has
all 39 capabilities, from checkouts to tax, usage billing and Connect.
PayPal has a smaller set: checkout, refunds,
subscriptions, webhooks and raw requests. A call the provider cannot do answers
MishkaPay.Errors.Unsupportedbefore any request. - 🌐 Many sites, one install: every call
names its tenant (a site). A keys plugin answers each site's keys at runtime, never from
config.exs, so a site's new keys need no restart. - 🧱 With or without Ash: the core works on plain
structs built with GuardedStruct. With Ash, the
MishkaPay.Ash.Resourceextension keeps payments, subscriptions, customers, disputes and more in your own resources, kept current from webhooks. - 📬 Verified webhooks: one endpoint per site checks each signature with that site's secret. With Ash, an inbox stores each event once and works it as an AshOban job with retries.
- 🔁 Subscriptions: trials, plan and quantity changes with a preview of the bill, paused collection, cancel and resume, and schedules planned ahead.
- 🧾 Tax and invoices and usage billing: Stripe Tax, one-off bills, credit notes and meters.
- 🏬 One platform, many sellers: Stripe Connect with Accounts v2, application fees, transfers and payouts.
- 🧩 Every extension point is an event: a checkout gate (
mishka_pay:checkout:before), webhook listeners, andmishka_pay:<kind>:changedafter every change.MishkaPay.PubSubsends them to Phoenix PubSub in one line. - 🚦 Plain errors and telemetry: every
call answers
{:ok, struct}or a typed error with a plain message for people. No telemetry event carries a key or a buyer's details. - 🧪 A test kit: stub every provider
request per test, deliver signed webhooks and run Stripe's mock server, in
async: truetests. - 🤖 Rules for coding agents:
usage-rules.mdand amishka-payskill ship with the package, so an agent writes payment code with calls that exist.
🚀 Get started
Follow Get Started. In short, in a Phoenix project on Elixir 1.20 or newer:
mix igniter.install mishka_pay
It adds the package, the plugin registry, a keys plugin, the webhook endpoint before
Plug.Parsers and the test setup. Add --ash for the Ash resources and --pubsub for
broadcasts. To set it up by hand, add the package to mix.exs. A pre-release is matched only
when you name it:
{:mishka_pay, "~> 0.0.1"}Give it a sandbox key and sell:
export STRIPE_SECRET_KEY=sk_test_...
{:ok, checkout} =
MishkaPay.checkout(%{
provider: "stripe",
items: [%{name: "Elixir ebook", amount: %{amount: "19.99", currency: "USD"}}],
success_url: url(~p"/thanks") <> "?session_id={CHECKOUT_SESSION_ID}",
cancel_url: url(~p"/cart"),
reference: order.id
})
redirect(conn, external: checkout.url)When the buyer comes back, read the payment with MishkaPay.fetch_checkout/3 and
MishkaPay.fetch_payment/3 before you give access.
📚 Documentation
- Tutorial: Get Started
- How-to guides:
- Take a one-time payment
- Sell and manage subscriptions
- Refund, hold and capture a payment
- Save customers and cards, and open the billing portal
- Receive and verify webhooks
- Run many sites on one Stripe platform
- Count tax, send invoices and issue credit notes
- Bill by usage with meters
- Take payments with PayPal
- Test code that takes payments
- Keep payments in Ash resources and Mishka CMS
- Concepts: How Mishka Pay works
- Reference: Capabilities by provider, Keys and options, Errors and telemetry
Short guides also ship with the package in guides/, and every module has its own docs on
HexDocs.
🛍️ The demo shop
examples/shop is a
Phoenix shop on your Stripe sandbox that shows every feature. With PayPal sandbox keys it takes
PayPal too. Each part of the page carries a data-testid for browser tests.
📰 Read more
- One Elixir API for Stripe and PayPal: Meet Mishka Pay, the announcement post.
- The Mishka blog, for releases and articles.
💬 Community and support
- Chat with the team and other users on Discord.
- Report a bug or ask a question in GitHub issues.
- For a provider of your own, a payment integration or priority support, hire the Mishka team.
💖 Support the project
Mishka Pay is free and open source. You can support its development through GitHub Sponsors or Buy Me a Coffee.
📜 License
Apache License 2.0. See LICENSE.