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, :portal and :payment_method. Stripe has all three. PayPal has none.

Create a customer

elixir
{: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.

elixir
{: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

elixir
{: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.

elixir
{: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.

elixir
{: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