Save customers and cards, and open the billing portal
v0.0.1
A returning buyer pays faster when you keep one provider customer for each user. This guide shows how to create a customer, save a card without a charge, list and change saved cards, send the buyer to the billing portal and erase a customer when they ask. The calls are the same on every site. A Mishka CMS site keeps the customer id next to its own user and passes the site id as the tenant.
Before you begin
- Mishka Pay installed with a Stripe key. See Get Started.
- A place to keep the provider's customer id with your user, such as a column.
- The provider needs
:customer,:portaland:payment_method. Stripe has all three. PayPal has none.
Create a customer
{:ok, customer} =
MishkaPay.create_customer(%{
provider: "stripe",
tenant: site.id,
email: user.email,
name: user.name,
reference: user.id
})reference is your user id. Sent again within a day with the same fields, it answers the same customer instead of making a second one. With other fields Stripe refuses it, and the error is Errors.Rejected with code "idempotency_error". Change a customer with update_customer/1, and read one with fetch_customer/3.
By default a Stripe customer is an Accounts v2 account with the customer configuration (an acct_... id). Set customer_api: :v1 in the site's keys, or api: :v1 on a customer, for a classic Customer (cus_...). Every call takes either id. See Keys and options.
Name the customer on a later checkout with customer: %{id: customer.id}, and the buyer pays as that customer. Stripe Managed Payments sells to no customer account, so a checkout for an acct_ customer with merchant_of_record: true is Errors.Invalid on :customer. Use merchant_of_record: false or a v1 customer for that buyer.
Save a card without charging
A checkout in mode: :setup saves a card and charges nothing. It needs a currency and no items.
{:ok, checkout} =
MishkaPay.checkout(%{
provider: "stripe",
tenant: site.id,
mode: :setup,
currency: "usd",
customer: %{id: customer.id},
success_url:
url(~p"/account") <>
"?session_id={CHECKOUT_SESSION_ID}",
cancel_url: url(~p"/account")
})Without customer, Stripe makes one. Read the checkout back to get :setup_intent_id and :payment_method_id. Options of a sale, such as discounts, tax, a trial or an invoice, are refused in setup mode.
List and change saved cards
{:ok, page} =
MishkaPay.list_payment_methods("stripe", site.id,
customer_id: customer.id
)
MishkaPay.set_default_payment_method(
"stripe",
customer.id,
"pm_...",
site.id
)
MishkaPay.detach_payment_method("stripe", "pm_...", site.id)Each item is a %MishkaPay.Customer.PaymentMethod{} with its type, card brand, last four digits and expiry. The default method is the one invoices and subscriptions charge. detach_payment_method/3 is for good: Stripe never attaches that payment method again. Business buyers can add a VAT or other tax id with create_tax_id/4.
Send the buyer to the portal
The billing portal is a Stripe-hosted page where the buyer sees cards, invoices and subscriptions.
{:ok, portal} =
MishkaPay.portal_session(%{
provider: "stripe",
tenant: site.id,
customer_id: customer.id,
return_url: url(~p"/account")
})
redirect(conn, external: portal.url)Make a session per click. Add flow: to open it on one task: :payment_method_update, :subscription_cancel or :subscription_update (the last two also need subscription_id:).
What the buyer may do in the portal is a portal configuration kept at Stripe. Without one, Stripe's default applies.
{:ok, teams} =
MishkaPay.create_portal_configuration(%{
provider: "stripe",
tenant: site.id,
name: "Teams",
headline: "Acme billing",
invoice_history: true,
payment_method_update: true,
customer_update: [:email, :tax_id],
subscription_cancel: :at_period_end,
subscription_update: [:price, :quantity],
proration: :create_prorations,
plans: [
%{
product_id: team.id,
price_ids: [monthly.id, yearly.id]
}
]
})
MishkaPay.portal_session(%{
provider: "stripe",
tenant: site.id,
customer_id: customer.id,
return_url: url(~p"/account"),
configuration: teams.id
})Every field is optional. A list such as customer_update turns its feature on, and [] turns it off. subscription_cancel is :immediately, :at_period_end or :off. A configuration is never deleted. Set active: false with update_portal_configuration/1.
Erase a customer
When a person asks to be erased, call MishkaPay.delete_customer("stripe", customer.id, site.id). It cannot be undone and it ends their running subscriptions at once. Past payments and invoices stay at Stripe, so also delete your own copy of their details.
Next steps
- Sell and manage subscriptions: the plans a customer buys.
- Count tax, send invoices and issue credit notes: bills for a customer.
- Keep payments in Ash resources and Mishka CMS: customers as Ash rows with a portal action.