Example: Payments & Payouts
A complete playbook for money-owed-to-merchant tickets, with the fields filled in exactly as you would paste them.
Money that a merchant expected and did not receive. High volume, high emotion, and almost always explained by one of four configuration states — which makes it the best playbook to write first.
Fields
Name
Payments & PayoutsDescription
Tickets about money owed to a merchant that has not arrived: payouts, settlement
timing, missing transfers, payout account setup, and disputes about amounts.Routing hints
payout, payouts, settlement, transfer, deposit, "money not received", "where is my
money", "haven't been paid", bank account, ACH, "payout pending", "payout failed",
minimum thresholdTriage instructions
A payout is a scheduled transfer of settled funds to a merchant's bank account.
Merchants report "missing payout" for three distinct problems: the payout never
generated, it generated but was held, or it sent and their bank has not posted it.
Distinguish which one before anything else.
Check in this order and stop as soon as one explains it:
1. payout_configs — is there a row for this merchant at all? A missing row is the
single most common cause and the cheapest check.
2. payout_configs.bank_verified — false silently holds every payout. Very common
right after a merchant changes bank details.
3. payouts for the reported period — did one generate? Note its status and amount.
If status is `sent` with a processor reference, the money has left us.
4. payout_attempts for the failure reason, if a payout exists but did not send.
5. Only then search the app-payments-* logs and Sentry for the send attempt,
filtering on merchant_id.
Known causes, most to least common:
- missing payout_configs row (merchant never completed payout setup)
- bank_verified = false after a bank detail change
- balance below the merchant's minimum payout threshold — check the threshold on the
config, not the default
- a processor-side hold, visible only as a payout.hold event in the logs
Conclusions:
- If a payout exists with status `sent` and a processor reference, say so explicitly
and quote the reference — support should point the merchant at their own bank, and
this is the most common false alarm.
- Do not report "payouts are broken" for a single merchant's configuration problem.
Check whether other merchants paid out in the same window before claiming anything
systemic.
- If none of the five checks explains it, report which checks you completed and what
each returned. Do not speculate about processor-side causes you could not observe.Data sources
org-postgres, org-opensearch, org-sentryVisibility
Everyone in the organization.
Why it is scoped this way
Postgres holds the state (payout_configs, payouts, payout_attempts), OpenSearch
holds the send-attempt logs, and Sentry holds exceptions from the payout worker.
Metrics and Kubernetes are deliberately excluded: a single merchant's missing payout is a data problem, not an infrastructure one, and letting the agent wander into cluster health on every payout ticket costs money and finds nothing. If payouts are broken for everyone, that is a Platform Reliability ticket.
Tuning it
Watch for tickets that land here but are really about card payments failing at checkout — customers use "payment" for both. If that happens, sharpen this description toward merchant receives money and lean on Checkout & Orders for customer pays money.