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.

Read the Mishka Pay docs mix igniter.install mishka_pay
  1. 01Your app

    Phoenix and Ash. Each call names its site.

  2. 02Mishka Pay

    One set of calls, whichever provider answers.

  3. 03Plugins

    A keys plugin answers each site's keys. Providers are Mishka Installer plugins.

  4. 04Providers

    Stripe and PayPal.

Fig. 0Pick a provider and every drawing below follows it.

Sheet 01 Round trip

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.

Your appPhoenix · AshMishkaPay.checkout/1
Keys pluginthis site's keys, at runtime, never in config
Provider pluginone for each provider, built on Mishka Installer
Webhook plugchecks the site's secret
Inboxeach event stored once
AshOban jobworks the inbox
Your Ash rowsPayment · Subscription · Customer
Fig. 1The parts with a colored edge run in Mishka Pay. Your app sits on one side and the provider on the other.
Sheet 02 Many sites

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 CMS
One install MishkaPay.checkout(%{tenant: site_id, ...})
shop.example tenant: "shop"
Keys Stripe••••••••
Webhook secret secret•••••• /pay/webhooks/stripe/shop
Rows Payment:paidPayment:refunded
news.example tenant: "news"
Keys PayPal••••••••
Webhook secret secret•••••• /pay/webhooks/paypal/news
Rows Subscription:activePayment:paid
club.example tenant: "club"
Keys Stripe•••••••• PayPal••••••••
Webhook secret secret•••••• /pay/webhooks/stripe/club
Rows Subscription:trialingPayment:pending
Fig. 2One install, three sites, nothing shared between them.
Sheet 03 Checkout Answered by

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.

  1. 1Your page starts the checkout and redirects.
  2. 2The buyer pays on the provider's page.
  3. 3They come back to your success URL.
Fig. 3aHosted. Your page, the provider's page, then your page again.

The same call, with ui_mode: :embedded

Fig. 3bEmbedded. The provider's form sits inside your own page.
Sheet 04 Subscriptions Answered by

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.

Subscriptions in Mishka Pay
  1. Trial The checkout opens the plan with a trial.
    :trialing trial_end
  2. Active The trial ends and Starter bills its first period.
    :active current_period_end
  3. Plan change Preview what it bills, then move to Pro.
    :active preview_subscription_change/1
  4. Cancel at period end Pro stays on until the paid period runs out.
    :active cancel_at_period_end
  5. Ended The period is over.
    :canceled

subscribed?Hover or tap a phase to see what it answers there.

Fig. 4The band is the plan the customer is on. The strip under it is what subscribed? answers.
Sheet 05 Refunds and holds Answered by

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.

Refund MishkaPay.refund/1
:paid The buyer paid in full.
:partially_refunded Part of it went back.
:refunded All of it went back.
Hold, then capture capture: :manual
:authorized Held on the card at checkout.
:paid Captured later, all or part.
:canceled Or let go, with nothing taken.
Fig. 5Solid is money you keep. Hatched is money that went back. Ticks are money on hold.
Sheet 06 Webhooks Answered by

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 Pay
01Verify
Signed request POST /pay/webhooks/stripe/shop
  • Current secretMatches this site's secret.
  • Previous secretOn Stripe, still accepted while you roll.
  • Any other signatureGoes no further.
02Store once 04 Replay missed events
event_idtypestatus

statusPick a row to see what its status means.

03Process
AshOban jobTakes each pending event, with retries.
Your rows Payment:paid Subscription:active
Fig. 6A second copy of an event never gets in. A failed one waits in the inbox.
Sheet 07 Connect Answered by

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 Pay
Platform your Stripe account
Seller A account_link/1 onboarding link sent
Seller B create_connected_account/1 connected
Seller C create_connected_account/1 connected
One sale through Seller B
Application fee Stays with the platform. Transfer Goes to Seller B, then a payout sends it to their bank.
Fig. 7One sale, split in two: a fee for the platform and a transfer for the seller.
Sheet 08 Capabilities

Unsupported 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
Board for
callMishkaPay.create_transfer/1 with provider: "stripe" answer{:ok, %MishkaPay.Transfer{}} requestsent with this site's keys
Checkout
Money back
Subscriptions
Billing
Tax
Connect
Risk
Webhooks
Anything else

Pick a keyHover or tap a key to see its call and who answers it.

Fig. 8Lit keys are answered. Hatched keys are refused before any request.
Sheet 09 Your rows

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.

Mishka Pay with Ash and Mishka CMS
extensions: [MishkaPay.Ash.Resource]

mishka_pay do
  kind :payment
end

MishkaPay.Ash.subscribed?(
  MyApp.Pay.Subscription,
  user,
  tenant: site.id
)
Siteyour tenant
Paymentkind :payment providerstringprovider_idstringstatus:paidamountdecimalcurrencystringreferencestringtenantSiteuser_idUser
Subscription:subscription provider_idstringstatus:activeplanstringcurrent_period_endtimecancel_at_period_endbooltrial_endtimetenantSiteuser_idUser
Customerkind :customer provider_idstringemailstringnamestringphonestringreferencestringmetadatamaptenantSiteuser_idUser
Disputekind :dispute provider_idstringpayment_idstringstatusatomreasonstringamountdecimalcurrencystringevidence_due_bytimetenantSite
Inboxkind :inbox providerstringevent_idstringtypestringobject_idstringstatus:pendinglast_errorstringprocessed_attimetenantSite
Useryour user resource
Fig. 9The rows Mishka Pay keeps for you, and the site and user they belong to.
Sheet 10 First call

Install it, then make the first call

mix igniter.install mishka_pay or add it to your deps {:mishka_pay, "~> 0.0.0"}
Read the Mishka Pay docs
Elixir
{:ok, checkout} =
  MishkaPay.checkout(%{
    provider: "stripe",
    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", payment_id, site_id)

Stripe or PayPal.

This site's keys answer.

Your own order id.

Read the payment back before you deliver.

Fig. 10One checkout, then the payment read back from the provider.
General notes

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.

Revision

v0.0.0 · Stripe and PayPal · ready for production

Sheet 11 Newsletter

Mishka newsletter

New patterns and releases, once a month.

Release notes, recipes and product updates from the team building Mishka. No spam, unsubscribe anytime.

  • once a month
  • no spam
Issue
Once a month
Inside
Release notes, recipes, product updates
From
The team building Mishka
Unsubscribe
Anytime