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.
{: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 anex_moneyvalue. 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 withcreate_customer/1) or byemail, never both. - An item can also be a catalog price:
%{id: price.id, quantity: 1}. Keep prices in the catalog withcreate_product/1andcreate_price/1, and name them with alookup_keyso code never holds aprice_...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.
{: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) oramount_off, one of them.duration: :repeatingneedsduration_in_months. automatic_tax: truecounts the tax with Stripe Tax. Turn Stripe Tax on in the Dashboard first. See Count tax, send invoices and issue credit notes.invoice: truemakes an invoice for the one-time payment. Whether Stripe emails receipts is a Dashboard setting.expires_atmust be 30 minutes to 24 hours from now.expire_checkout/3ends an open checkout when the buyer walks away, so held stock is free again.- Other options are
locale,customer_creation,phone,terms,descriptionandstatement_suffix. A provider that cannot send an option answersErrors.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.
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: :embeddedand a singlereturn_urlin place ofsuccess_urlandcancel_url. The answer has a:client_secretand 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/1on the server. Your page uses Stripe.js to mount the Payment Element with the intent's:client_secretand the site'spublishable_key, and confirms it in the browser. Card numbers never pass through your server. Read the intent withfetch_payment/3before giving access.create_setup_intent/1saves 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:
{: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 tookThe 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.
Sell with a link instead
A payment link sells catalog prices to anyone who opens it. Make it once and put it in a page, an email or a QR code. Each buyer still gets their own checkout, so sales arrive through the same webhooks.
{:ok, link} =
MishkaPay.create_payment_link(%{
provider: "stripe",
tenant: site.id,
items: [%{id: price.id, quantity: 1}],
success_url: url(~p"/thanks"),
max_purchases: 100,
inactive_message: "Sold out"
})
MishkaPay.PaymentLink.url(link,
reference: order.id,
email: user.email
)A link cannot be deleted. Turn it off with update_payment_link(%{provider: "stripe", tenant: site.id, id: link.id, active: false}).
Next steps
- Refund, hold and capture a payment: pay later with
capture: :manual, and give money back. - Sell and manage subscriptions: the same checkout with
mode: :subscription. - Save customers and cards, and open the billing portal.
- Errors and telemetry: what each failure means.