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.
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
endinspect/1 on the keys shows only the provider, the tenant and the mode, so a key never reaches a log line.
Key fields
| Field | Values | Meaning |
|---|---|---|
secret_key | String, required | The provider's secret key. For PayPal, the app's secret. |
publishable_key | String | The key a browser may see, such as Stripe.js's. For PayPal, the app's client id. |
webhook_secret | String | Stripe: whsec_.... PayPal: the webhook id (WH-...). |
webhook_secrets | List of strings | Older secrets still accepted while a rolled one runs out. Stripe only. |
mode | :test (default), :live | Test or live. Strings "test" and "live" are accepted. |
merchant_of_record | true, false, absent | Stripe Managed Payments for this site. Absent means the Stripe account's own default. A checkout's own value wins. |
automatic_tax | Boolean | Count tax on every checkout and payment link with Stripe Tax. A checkout's own choice wins. |
refunds | :once (default), :many | One refund per payment, or part refunds until it is used up, each with its own reference. |
billing_mode | :flexible (default), :classic | How new subscriptions count prorations and bill. A checkout's or a schedule's own wins. |
proration_discounts | :itemized (default), :included | With the flexible mode, whether a proration shows the full amount and its discount, or the amount after the discount. |
account_id | acct_... | 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), :v1 | Stripe Accounts v2 or v1 for connected accounts. A call's api: wins. |
customer_api | :v2 (default), :v1 | A 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), :snapshot | The 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), :v1 | Stripe event destinations (/v2/core/event_destinations), or /v1/webhook_endpoints, snapshot events only. A call's api: wins. |
extra | Map | Whatever a provider you write needs. |
Choices that override the keys
| Where | Option | Effect |
|---|---|---|
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/3 | api: :v1 | :v2 | The customer API for this call. |
| Connected accounts, account links, close, read, list | api: :v1 | :v2 | The Accounts API for this call. |
list_events/3, replay_events/3 | events: :thin | :snapshot | Which event API to read. |
| Checkout, schedule | billing_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. |
| Checkout | capture: | :automatic (Stripe's automatic_async), :automatic_sync (automatic), :manual. Left out, Stripe's default applies. |
| Checkout | ui_mode: | :hosted or :embedded. |
| Checkout | mode: | :payment, :subscription or :setup. |
| Every list call | limit:, 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
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"providerschooses which providers the application starts. All of them by default.webhook_timeoutis how long listeners may take before the endpoint answers 500. The default is 15 seconds.files_urlpoints file uploads elsewhere. With onlybase_urlset for Stripe's mock server, uploads go there too.
Mix tasks
| Task | Options | What it does |
|---|---|---|
mix igniter.install mishka_pay | --ash, --admin, --pubsub | Sets 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, --domain | Checks 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-accounts | Makes 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), --events | Delivers again the events a site missed. Stripe keeps 30 days. |
mix mishka_pay.stripe.check_version | none | Fails 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-run | Deletes 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: :livewithsk_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. Runmix mishka_pay.check --tenant <site> --webhook-url ... --domain MyApp.Payand fix what fails. - Give access from the provider's word. Read the payment or subscription back with
fetch_payment/3orfetch_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_taxcounts anything. - Emails. Receipts and invoice emails are Stripe Dashboard settings (Customer emails).
- Refunds. Choose
:onceor:manyfor 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_inboxqueue must run in production. - After an outage. Replay events with
mix mishka_pay.replay_events.