Take a one-time payment

v0.0.1

A one-time payment in Mishka Pay, the Elixir payment SDK, is a checkout: you describe what the buyer is paying for, send them to the provider's page and read the payment back afterwards. This guide shows how to build the checkout, add discounts, tax, shipping and a customer, choose between a hosted page, an embedded form and your own card form, and give access only after the money is there. It uses Stripe. For PayPal see Take payments with PayPal.

Before you begin

  • Mishka Pay installed and a key for the site. Do Get Started first if you have not.
  • A Stripe sandbox key (sk_test_...). Run everything on the sandbox until it works.
  • A page that can receive the buyer after payment, and one for a canceled checkout.

Build the checkout

Call MishkaPay.checkout/1 with a map. It answers {:ok, %MishkaPay.Checkout{}} or {:error, error}. Redirect the buyer to checkout.url.

elixir
{:ok, checkout} =
  MishkaPay.checkout(%{
    provider: "stripe",
    tenant: site.id,
    items: [
      %{
        name: "Elixir ebook",
        amount: %{amount: "19.99", currency: "USD"},
        quantity: 1,
        tax_code: "txcd_10302000"
      }
    ],
    success_url:
      url(~p"/thanks") <>
        "?session_id={CHECKOUT_SESSION_ID}",
    cancel_url: url(~p"/cart"),
    reference: order.id,
    customer: %{email: user.email}
  })

redirect(conn, external: checkout.url)
  • Money is %{amount: "19.99", currency: "USD"} or an ex_money value. The amount is a string with at most the currency's own decimals. A float is refused.
  • Reference is your order id. It makes the idempotency key, so a double click never opens two checkouts, and it comes back on the payment.
  • Tenant is the site. In Mishka CMS, where each site keeps its own keys, pass the site id on every call. A project with one site may leave it out.
  • Customer names the buyer by id (a customer you made with create_customer/1) or by email, never both.
  • An item can also be a catalog price: %{id: price.id, quantity: 1}. Keep prices in the catalog with create_product/1 and create_price/1, and name them with a lookup_key so code never holds a price_... id by hand.

Add discounts, tax and checkout options

Make a coupon and a promotion code once. Then either let the buyer type the code or apply it for them, not both.

elixir
{:ok, coupon} =
  MishkaPay.create_coupon(%{
    provider: "stripe",
    tenant: site.id,
    name: "Spring",
    percent_off: 20,
    duration: :once
  })

{:ok, code} =
  MishkaPay.create_promotion_code(%{
    provider: "stripe",
    tenant: site.id,
    coupon_id: coupon.id,
    code: "SPRING20"
  })

MishkaPay.checkout(%{
  # provider, items, URLs and reference as above
  allow_promotion_codes: true,
  # or: discounts: [%{promotion_code_id: code.id}]
  automatic_tax: true,
  billing_address: :required,
  tax_id_collection: true,
  invoice: true,
  expires_at: DateTime.add(DateTime.utc_now(), 3600)
})
  • A coupon takes percent_off (above 0, up to 100) or amount_off, one of them. duration: :repeating needs duration_in_months.
  • automatic_tax: true counts the tax with Stripe Tax. Turn Stripe Tax on in the Dashboard first. See Count tax, send invoices and issue credit notes.
  • invoice: true makes an invoice for the one-time payment. Whether Stripe emails receipts is a Dashboard setting.
  • expires_at must be 30 minutes to 24 hours from now. expire_checkout/3 ends an open checkout when the buyer walks away, so held stock is free again.
  • Other options are locale, customer_creation, phone, terms, description and statement_suffix. A provider that cannot send an option answers Errors.Unsupported. It never drops one without telling you.

Ship a product

Ask for an address and offer shipping rates on a one-time checkout. The provider needs the :shipping capability, and Stripe has it.

elixir
MishkaPay.checkout(%{
  # ...
  shipping_countries: ["NL", "DE"],
  shipping_rates: [
    "shr_...",
    %{
      name: "Post",
      amount: %{amount: "5", currency: "USD"},
      min_days: 2,
      max_days: 5
    }
  ]
})

Read back, the checkout has :shipping_address, :shipping_rate_id and :amount_shipping. Stripe refuses shipping where Managed Payments is on, so send merchant_of_record: false with it. A shipping rate's amount cannot change once set. Make a new rate.

Pick where the buyer pays

There are three places.

  • Stripe's hosted page. The default. Redirect to checkout.url.
  • Embedded. Add ui_mode: :embedded and a single return_url in place of success_url and cancel_url. The answer has a :client_secret and no :url. Your page loads Stripe.js and mounts the form with that secret. Give the secret to that buyer's page only. Put {CHECKOUT_SESSION_ID} in the return URL to read the session back.
  • Your own card form. Call create_payment_intent/1 on the server. Your page uses Stripe.js to mount the Payment Element with the intent's :client_secret and the site's publishable_key, and confirms it in the browser. Card numbers never pass through your server. Read the intent with fetch_payment/3 before giving access. create_setup_intent/1 saves a card the same way without a charge.

A checkout is always a Stripe Checkout Session. The own-form path is the only one that works with a PaymentIntent directly.

Read the payment and give access

Back on the success page, read the checkout and then the payment:

elixir
{:ok, %{payment_id: payment_id}} =
  MishkaPay.fetch_checkout("stripe", session_id, site.id)

{:ok, payment} =
  MishkaPay.fetch_payment("stripe", payment_id, site.id)

payment.status      #=> :paid
payment.reference   #=> order.id
payment.amount      #=> the money Stripe took

The checkout has a :payment_id only once Stripe took the money. A checkout read back also shows :amount_total, :amount_tax and :amount_discount. Some payments finish later, such as a bank debit. For those, listen for the webhook and sync then. See Receive and verify webhooks.

Take access away if the payment later reads :refunded, :failed or :canceled, or if disputed is true.

Next steps