Keys and options

v0.0.1

This page lists everything a site's keys plugin can answer, the per-call API choices that override it, the Mix tasks Mishka Pay ships and the settings to check before a site takes real money. Mishka Pay reads all of it at runtime on every call, never from config.exs, so each site in a Mishka CMS install carries its own and a change applies to the next call. It describes version 0.0.1.

Keys plugin

A keys plugin uses MishkaPay.Credentials and answers a map, or nil for a site without keys (the call is then MishkaPay.Errors.MissingCredentials). The answer may use atom or string keys. Its own :provider and :tenant are ignored, since they always come from the call. When several plugins answer, the first one in order of :priority (50 by default) wins.

elixir
defmodule MyApp.Pay.Keys do
  use MishkaPay.Credentials

  @impl MishkaPay.Credentials
  def credentials("stripe", site_id) do
    case MyApp.Sites.payment_settings(site_id) do
      %{stripe_secret_key: key} = s when is_binary(key) ->
        %{
          secret_key: key,
          webhook_secret: s.stripe_webhook_secret,
          refunds: :once,
          automatic_tax: s.stripe_tax?,
          merchant_of_record: s.merchant_of_record
        }

      _no_keys ->
        nil
    end
  end

  def credentials(_provider, _site_id), do: nil
end

inspect/1 on the keys shows only the provider, the tenant and the mode, so a key never reaches a log line.

Key fields

FieldValuesMeaning
secret_keyString, requiredThe provider's secret key. For PayPal, the app's secret.
publishable_keyStringThe key a browser may see, such as Stripe.js's. For PayPal, the app's client id.
webhook_secretStringStripe: whsec_.... PayPal: the webhook id (WH-...).
webhook_secretsList of stringsOlder secrets still accepted while a rolled one runs out. Stripe only.
mode:test (default), :liveTest or live. Strings "test" and "live" are accepted.
merchant_of_recordtrue, false, absentStripe Managed Payments for this site. Absent means the Stripe account's own default. A checkout's own value wins.
automatic_taxBooleanCount tax on every checkout and payment link with Stripe Tax. A checkout's own choice wins.
refunds:once (default), :manyOne refund per payment, or part refunds until it is used up, each with its own reference.
billing_mode:flexible (default), :classicHow new subscriptions count prorations and bill. A checkout's or a schedule's own wins.
proration_discounts:itemized (default), :includedWith the flexible mode, whether a proration shows the full amount and its discount, or the amount after the discount.
account_idacct_...The connected account the site acts for. Sent as Stripe-Account (Stripe-Context on API v2 paths). Left out, the site is the account that owns the key. It comes only from these keys.
connect_api:v2 (default), :v1Stripe Accounts v2 or v1 for connected accounts. A call's api: wins.
customer_api:v2 (default), :v1A customer is an Accounts v2 account with the customer configuration (acct_...), or a v1 Customer (cus_...). A customer's or a call's api: wins.
events:thin (default), :snapshotThe kind of event the site's endpoint is set up for, and the one list_events/3 and replay_events/3 read. A call's events: wins. The webhook takes both whatever this says.
webhook_api:v2 (default), :v1Stripe event destinations (/v2/core/event_destinations), or /v1/webhook_endpoints, snapshot events only. A call's api: wins.
extraMapWhatever a provider you write needs.

Choices that override the keys

WhereOptionEffect
Any Stripe call (MishkaPay.request/1)options: %{api_version: "...", expand: [...]}Sends that Stripe-Version and expand[] for this call only. Typed calls always use the pinned version.
A customer, list_customers/3, search_customers/3api: :v1 | :v2The customer API for this call.
Connected accounts, account links, close, read, listapi: :v1 | :v2The Accounts API for this call.
list_events/3, replay_events/3events: :thin | :snapshotWhich event API to read.
Checkout, schedulebilling_mode:, proration_discounts:Only on a subscription checkout or a new schedule. A one-time checkout and a schedule made from a subscription refuse them. proration_discounts with :classic is Errors.Invalid.
Checkoutcapture::automatic (Stripe's automatic_async), :automatic_sync (automatic), :manual. Left out, Stripe's default applies.
Checkoutui_mode::hosted or :embedded.
Checkoutmode::payment, :subscription or :setup.
Every list calllimit:, after:1 to 100 (10 by default), and the cursor of the page before. Answers one MishkaPay.Page with :items, :has_more and :next. MishkaPay.Page.stream/1 reads every page lazily.

The pinned Stripe API version is MishkaPay.Providers.Stripe.version/0. A v2 list holds at most 20 items a page.

Application settings

elixir
config :mishka_pay, providers: [MishkaPay.Providers.Stripe]
# tests only
config :mishka_pay,
  req_options: [plug: {Req.Test, MishkaPay.Client}]

# milliseconds, per listener run
config :mishka_pay, webhook_timeout: 15_000

config :mishka_pay, MishkaPay.Providers.Stripe,
  files_url: "https://files.stripe.com"
  • providers chooses which providers the application starts. All of them by default.
  • webhook_timeout is how long listeners may take before the endpoint answers 500. The default is 15 seconds.
  • files_url points file uploads elsewhere. With only base_url set for Stripe's mock server, uploads go there too.

Mix tasks

TaskOptionsWhat it does
mix igniter.install mishka_pay--ash, --admin, --pubsubSets a Phoenix project up. --ash adds the domain and resources, --admin the admin objects (turns --ash on), --pubsub a broadcast plugin.
mix mishka_pay.check--provider, --tenant, --webhook-url, --domainChecks a site's provider, keys, webhook secret and endpoint, Ash listeners and inbox queue. Fails when one does not pass.
mix mishka_pay.stripe.webhook_endpoint--url, --tenant, --check, --events, --api, --connected-accountsMakes a site's Stripe endpoint with the events Mishka Pay acts on, or adds the events it lacks.
mix mishka_pay.replay_events--provider, --tenant, --since (required), --type (repeatable), --eventsDelivers again the events a site missed. Stripe keeps 30 days.
mix mishka_pay.stripe.check_versionnoneFails when Stripe has published an API version newer than the pin. Needs no keys.
mix mishka_pay.stripe.clean_clocks--tenant, --older-than, --name, --dry-runDeletes old Stripe test clocks with their customers and subscriptions. Test keys only.

Settings to check before going live

  • Live keys only in production. Each site's keys plugin answers mode: :live with sk_live_ keys. Test clocks and the cleanup task refuse live keys.
  • A webhook for every site. One endpoint per site at https://your-host/pay/webhooks/stripe/<site> with that site's secret. Run mix mishka_pay.check --tenant <site> --webhook-url ... --domain MyApp.Pay and fix what fails.
  • Give access from the provider's word. Read the payment or subscription back with fetch_payment/3 or fetch_subscription/3, never from a success URL or a webhook body.
  • Managed Payments. Each price needs a tax_code. Stripe then always makes an invoice and refuses a payment link with invoices off. Turn it on or off per site (merchant_of_record) or per checkout.
  • Stripe Tax. Turn it on in the Dashboard (origin address, registrations) before automatic_tax counts anything.
  • Emails. Receipts and invoice emails are Stripe Dashboard settings (Customer emails).
  • Refunds. Choose :once or :many for each site.
  • Disputes. Take back access while a payment is disputed, and answer before evidence_due_by.
  • Oban. With the Ash layer, the mishka_pay_inbox queue must run in production.
  • After an outage. Replay events with mix mishka_pay.replay_events.