Get Started
v0.0.1
Mishka Pay is an Elixir payment SDK. You build a checkout, send the buyer to the provider's page, and read the payment back when the buyer returns. Stripe is the full provider, and PayPal has a smaller adapter. Mishka Pay runs inside Mishka CMS, where every site keeps its own provider keys, and it works in any Phoenix app. This tutorial installs version 0.0.1, sells one product on the Stripe sandbox and reads the payment back.
What you will build
A Phoenix app with one route that opens a Stripe Checkout page for a book that costs 19.99 USD, and one route the buyer lands on after paying. The second route asks Stripe if the money arrived before it says thank you.
Before you begin
- A Phoenix project on Elixir 1.20 or later.
- A Stripe sandbox and its secret key, which starts with
sk_test_. In the Stripe Dashboard open the account menu, choose Sandboxes, create one and copy the key from Developers, API keys. Use a sandbox, not live keys. - The Igniter installer.
mix igniter.installcomes from theigniter_newarchive, whichmix archive.install hex igniter_newadds.
Step 1: Install the package
Run the installer from the root of the project:
mix igniter.install mishka_payIt changes the project in five places and never twice:
- adds
{:mishka_pay, "~> 0.0.1"}tomix.exs; - supervises
MishkaPay.Registry, which starts the plugin registry of Mishka Installer when nothing else has, and a keys plugin calledYourApp.Pay.Keys; - mounts
plug MishkaPay.Webhook, at: "/pay/webhooks"in the endpoint, beforePlug.Parsers; - adds the test setup, so
MishkaPay.Test.stub_http/1can answer provider calls; - gives the plugin registry a folder under
.mnesia/for each environment.
If you prefer to do it by hand, see How Mishka Pay works for the parts and Receive and verify webhooks for the endpoint.
Step 2: Give the app a key
The generated keys plugin answers the Stripe key from the environment. Export your sandbox key in the shell that starts the server:
export STRIPE_SECRET_KEY=sk_test_...Mishka Pay never reads keys from config.exs. A keys plugin answers them at runtime, so one app can serve many sites, each with its own key. The plugin you just generated is the place to change that later. See Keys and options.
Step 3: Start a checkout
In a controller, build a checkout and redirect the buyer to the URL it returns:
def buy(conn, _params) do
{: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-1001"
})
redirect(conn, external: checkout.url)
endOpen the route. You land on a Stripe-hosted page that shows the book and its price. Pay with the test card 4242 4242 4242 4242, any future date and any CVC.
- The amount is a string and a currency. It is never a float.
{CHECKOUT_SESSION_ID}stays as written. Stripe replaces it with the real id when it sends the buyer back.referenceis your own id for the sale. The same reference never opens two checkouts, and it comes back on the payment. Always set it.- A
success_urlmust behttps, orhttponlocalhost.
Step 4: Read the payment when the buyer comes back
The success URL tells you the buyer returned. It does not tell you they paid. Ask Stripe:
def thanks(conn, %{"session_id" => session_id}) do
with {:ok, %{payment_id: payment_id}}
when is_binary(payment_id) <-
MishkaPay.fetch_checkout("stripe", session_id, nil),
{:ok, %MishkaPay.Payment{status: :paid} = payment} <-
MishkaPay.fetch_payment("stripe", payment_id, nil) do
render(conn, :thanks, payment: payment)
else
_not_paid -> redirect(conn, to: ~p"/cart")
end
endThe third argument is the tenant. A project with one site passes nil. A project with many sites passes the site id on every call.
A payment has a status of :pending, :requires_action, :authorized, :paid, :partially_refunded, :refunded, :failed or :canceled. It also carries the amount, the card brand and last four digits, the receipt URL and its refunds. Give access from the status, never from the success URL.
What you learned
You installed Mishka Pay, gave it a sandbox key, sent a buyer to Stripe with a checkout and read the payment back before saying thank you. The same two calls, checkout/1 and fetch_payment/3, work for every provider.
Next steps
- Take a one-time payment: discounts, shipping, an embedded form and pay later.
- Receive and verify webhooks: learn about payments that finish after the buyer has left.
- Sell and manage subscriptions: plans, trials, changes and cancels.
- Test code that takes payments: stub the provider in your tests.
- How Mishka Pay works: providers, keys and errors.