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.install comes from the igniter_new archive, which mix archive.install hex igniter_new adds.

Step 1: Install the package

Run the installer from the root of the project:

bash
mix igniter.install mishka_pay

It changes the project in five places and never twice:

  • adds {:mishka_pay, "~> 0.0.1"} to mix.exs;
  • supervises MishkaPay.Registry, which starts the plugin registry of Mishka Installer when nothing else has, and a keys plugin called YourApp.Pay.Keys;
  • mounts plug MishkaPay.Webhook, at: "/pay/webhooks" in the endpoint, before Plug.Parsers;
  • adds the test setup, so MishkaPay.Test.stub_http/1 can 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:

bash
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:

elixir
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)
end

Open 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.
  • reference is 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_url must be https, or http on localhost.

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:

elixir
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
end

The 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