Mishka Pay, the payment SDK for Elixir, drawn part by part
An open source SDK for Phoenix and Ash apps, with one set of calls for Stripe and PayPal. Built for Mishka CMS, where every site runs its own payments with its own keys; it works in any Phoenix app too.
$mix igniter.install mishka_pay
-
01Your app
Phoenix and Ash. Each call names its site.
-
02Mishka Pay
One set of calls, whichever provider answers.
-
03Plugins
A keys plugin answers each site's keys. Providers are Mishka Installer plugins.
-
04Providers
Stripe and PayPal.
Fig. 0Pick a provider and every drawing below follows it.
How a payment travels through your app
Your app names the site and makes the call. The answer comes back as a signed webhook and ends up in your own Ash rows.
MishkaPay.checkout/1
Every site holds its own keys
Mishka CMS runs many sites from one install. Mishka Pay gives each site its own keys, its own webhook secret and its own rows, and no site sees another's.
Mishka Pay with Ash and Mishka CMSMishkaPay.checkout(%{tenant: site_id, ...})
tenant: "shop"
tenant: "news"
tenant: "club"
Hosted checkout, or embedded in your page
Hosted checkout opens the provider's page and brings the buyer back to your success URL. Embedded checkout shows the provider's form inside your own page.
- 1Your page starts the checkout and redirects.
- 2The buyer pays on the provider's page.
- 3They come back to your success URL.
The same call, with ui_mode: :embedded
A subscription from its trial to its last day
Start with a trial, preview a plan change before you make it, and cancel at the end of the paid period. subscribed? answers along the way, so you can limit content by plan.
-
Trial The checkout opens the plan with a trial.:trialing
trial_end -
Active The trial ends and Starter bills its first period.:active
current_period_end -
Plan change Preview what it bills, then move to Pro.:active
preview_subscription_change/1refused on PayPal -
Cancel at period end Pro stays on until the paid period runs out.:active
cancel_at_period_endrefused on PayPal -
Ended The period is over.:canceled
subscribed?Hover or tap a phase to see what it answers there. Trial Answers true until trial_end. The status is :trialing. Active Answers true. Starter is paid for and the status is :active. Plan change Refused on PayPal. On Stripe: Answers true. The status stays :active on Pro. Cancel at period end Refused on PayPal. On Stripe: Answers true until current_period_end. Ended Answers false. The status is :canceled.
Give money back, or hold it first
Refund a payment in full or in part, and its row moves to :partially_refunded or :refunded. On Stripe you can also hold the money at checkout and capture it later.
MishkaPay.refund/1
capture: :manual
Each webhook is checked and stored once
plug MishkaPay.Webhook, at: "/pay/webhooks"Mount it before Plug.Parsers.
One plug takes every provider's webhooks. It checks each event with its site's secret and stores it once in an inbox, and an AshOban job processes it. On Stripe, events you missed can be replayed.
Webhooks in Mishka PayPOST /pay/webhooks/stripepaypal/shop
- Current secretMatches this site's secret.
- Previous secretOn Stripe, still accepted while you roll.
- Any other signatureGoes no further.
statusPick a row to see what its status means. processedThe job ran and your rows are updated.processedThe job ran and your rows are updated.kept onceThe same event came again, so the copy was dropped.pendingStored once, and waiting for the AshOban job.failedKept in the inbox for a retry.
Run a platform on Stripe Connect
Create connected accounts, send each seller an onboarding link, keep an application fee on every sale and move the rest with transfers and payouts.
Mishka Pay is on Stripe's newest API version, with Accounts v2 and v2 event destinations by default. The v1 paths stay as options.
A Connect platform with Mishka PayUnsupported calls never leave your app
Each provider says what it can do. Mishka Pay checks that first and returns a clear error before any request is sent. Stripe answers every key on this board. PayPal answers the ones that stay lit when you switch.
Provider capabilities in Mishka Pay
Pick a keyHover or tap a key to see its call and who answers it.
Hosted checkout
MishkaPay.checkout/1
Stripe answers it.
PayPal answers it.
Embedded checkout
MishkaPay.checkout/1 with ui_mode: :embedded
Stripe answers it.
PayPal refuses it before any request.
Hold and capture later
MishkaPay.capture_payment/2
Stripe answers it.
PayPal refuses it before any request.
Refunds
MishkaPay.refund/1
Stripe answers it.
PayPal answers it.
Credit notes
MishkaPay.create_credit_note/1
Stripe answers it.
PayPal refuses it before any request.
Subscriptions
MishkaPay.checkout/1 with mode: :subscription
Stripe answers it.
PayPal answers it.
Plan change with preview
MishkaPay.preview_subscription_change/1
Stripe answers it.
PayPal refuses it before any request.
Schedules
MishkaPay.create_subscription_schedule/1
Stripe answers it.
PayPal refuses it before any request.
Pause
MishkaPay.pause_collection/2
Stripe answers it.
PayPal refuses it before any request.
Customers
MishkaPay.create_customer/1
Stripe answers it.
PayPal refuses it before any request.
Billing portal
MishkaPay.portal_session/1
Stripe answers it.
PayPal refuses it before any request.
Invoices
MishkaPay.create_invoice/1
Stripe answers it.
PayPal refuses it before any request.
Usage billing with meters
MishkaPay.report_usage/1
Stripe answers it.
PayPal refuses it before any request.
Stripe Tax
MishkaPay.calculate_tax/1
Stripe answers it.
PayPal refuses it before any request.
Tax rates
MishkaPay.create_tax_rate/1
Stripe answers it.
PayPal refuses it before any request.
Connected accounts
MishkaPay.create_connected_account/1
Stripe answers it.
PayPal refuses it before any request.
Onboarding links
MishkaPay.account_link/1
Stripe answers it.
PayPal refuses it before any request.
Application fees
MishkaPay.list_application_fees/1
Stripe answers it.
PayPal refuses it before any request.
Transfers
MishkaPay.create_transfer/1
Stripe answers it.
PayPal refuses it before any request.
Payouts
MishkaPay.list_payouts/1
Stripe answers it.
PayPal refuses it before any request.
Disputes
MishkaPay.list_disputes/1
Stripe answers it.
PayPal refuses it before any request.
Fraud reviews
MishkaPay.list_fraud_reviews/1
Stripe answers it.
PayPal refuses it before any request.
Webhooks
plug MishkaPay.Webhook
Stripe answers it.
PayPal answers it.
Replay
MishkaPay.replay_events/2
Stripe answers it.
PayPal refuses it before any request.
Raw API call
MishkaPay.request/1
Stripe answers it.
PayPal answers it.
Payments live in your own Ash resources
Add the extension to a resource and say what kind it keeps. Webhooks keep its rows current, and subscribed? lets you limit content by plan.
extensions: [MishkaPay.Ash.Resource] mishka_pay do kind :payment end MishkaPay.Ash.subscribed?( MyApp.Pay.Subscription, user, tenant: site.id )
Install it, then make the first call
$mix igniter.install mishka_pay
or add it to your deps
{:mishka_pay, "~> 0.0.0"}
{:ok, checkout} = MishkaPay.checkout(%{ provider: "stripe""paypal", tenant: site_id, items: [ %{ name: "Elixir ebook", amount: %{amount: "19.99", currency: "USD"} } ], success_url: "https://shop.example/thanks", cancel_url: "https://shop.example/cart", reference: "order-1001" }) {:ok, %MishkaPay.Payment{status: :paid}} = MishkaPay.fetch_payment("stripe""paypal", payment_id, site_id)
1Stripe or PayPal.
2This site's keys answer.
3Your own order id.
4Read the payment back before you deliver.
Common questions about Mishka Pay
N1What is Mishka Pay?
Mishka Pay is an open source payment SDK for Elixir. Phoenix and Ash apps use one set of calls to take payments through Stripe or PayPal.
N2Which providers does it support?
Stripe and PayPal. Stripe covers checkout, subscriptions, refunds, held payments, invoices, tax, usage billing, Connect, disputes and a raw API call. PayPal covers checkout, refunds, subscriptions and webhooks.
N3Where do the keys live?
Each site keeps its own keys. A keys plugin answers them at runtime for the site a call names, so they never sit in config.
N4Do I need Mishka CMS to use it?
No. It was built for Mishka CMS, where every site runs its own payments, and it works in any Phoenix app too.
N5Is it ready for production?
Yes. Mishka Pay is ready for production with Stripe and PayPal. Start on a sandbox, then go through the settings to check before going live and switch to live keys.
v0.0.0 · Stripe and PayPal · ready for production