Failed transaction support
When to use it
Section titled “When to use it”- You run a wallet, bank app or payments business, and failed transactions flood support with "where is my money?".
- Your app or payment processor records each failure with a reason.
- A fraud or risk team must hear about suspected fraud quickly, and customers shouldn't get details in a message.
Where the data comes from
Section titled “Where the data comes from”| How | What |
|---|---|
| Events from your app or website (needs a developer) | Your app sends one event per failed transaction, with a reason and the channel it happened on. |
| A webhook from another system | No app changes? If your payment processor can post failure notices to a webhook source, map each to the same event name and properties. |
What it sets up
Section titled “What it sets up”| Kind | Name | What it does | Lands |
|---|---|---|---|
| Team | Fraud team | Calls customers about suspected-fraud failures. | Empty |
| Team | Fraud leads | Hears about fraud calls not made in time. | Empty |
| Team | Customer support | Helps customers whose transactions keep failing. | Empty |
| Segment | Repeated failed transactions | Two or more failed transactions in the last day. | Ready |
| Template | Transaction failed, try again (SMS) | Network or other failure. Reassures and says when a debit is reversed. | Ready |
| Template | Transaction failed, check your account (SMS) | Insufficient funds. Points to the app, never states a balance. | Ready |
| Template | Transaction over a limit (SMS) | Limit failure. How to raise the limit. | Ready |
| Template | Please call us (SMS) | Suspected fraud. No detail, only a call-us line. | Ready |
| Follow-up | Failed transaction: try again | Network, other or any unlisted reason; one try-again message at most every 6 hours. | Off |
| Follow-up | Failed transaction: check your account | Insufficient funds; a neutral message that points to the app. | Off |
| Follow-up | Failed transaction: over a limit | Limit failure; how to raise the limit. | Off |
| Follow-up | Failed transaction: suspected fraud | Suspected fraud; a call-us SMS and a fraud-team task due within the hour, escalated if missed. | Off |
| Follow-up | Failed transactions: repeated | Two failures in a day; a support task to help them. | Off |
The questions it asks
Section titled “The questions it asks”| # | Question | Default | Fills in |
|---|---|---|---|
| 1 | What should messages call your company? | none, must answer | org_name |
| 2 | Which number should customers call for help? (the number printed on your card or shown in the app) | ‹workspace phone› | support_phone |
| 3 | Where should messages send people to try again? (your app or a deep link) | none, must answer | app_url |
| 4 | Which team handles suspected fraud? | Fraud team | fraud_team |
| 5 | Which team helps customers whose transactions keep failing? | Customer support | support_team |
Other settings
Section titled “Other settings”These have defaults. Change any that don’t fit.
| Setting | Default | Key |
|---|---|---|
| Failed transaction event | Transaction Failed | failed_event |
| Hours a failed debit takes to be reversed | 24 | reversal_hours |
| Where in the app customers raise their limit | Profile, then Limits | limit_steps |
| Hours the fraud team has to call | 1 | fraud_due_hours |
| Who hears if the fraud call isn't made in time | Fraud leads | fraud_escalation_team |
| Hours support has to follow up repeated failures | 4 | repeat_due_hours |
| Greeting when a first name is missing | there | greeting_fallback |
Timings
Section titled “Timings”- A failure for the network or any other reason: an SMS straight away (at most one every 6 hours per customer).
- Insufficient funds and limit failures: a matching SMS straight away (at most one every 6 hours).
- Suspected fraud: a call-us SMS and a task for Fraud team, due in 1 hours and escalated to Fraud leads at the due time.
- Two or more failures in the same day: a task for Customer support, due in 4 hours.
Channels
Section titled “Channels”| Channel | Needed for | Before it can send |
|---|---|---|
| sms | Every message to customers | An SMS provider, or Origamy managed SMS after business verification (KYC). |
What you need to do
Section titled “What you need to do”- Send Transaction Failed for every failed transaction with a `reason` property that is one of insufficient_funds, network, limit, suspected_fraud or other, and a `channel` property (card, transfer, wallet and so on). A failure with no reason sends nothing. Never put an amount or account number in the event's properties that your team doesn't need.
- Check the reversal wording. The network message says a failed debit is returned within 24 hours: change that hour count to match your rails.
- For suspected fraud, send no detail. The SMS only asks the customer to call the number on their card or in your app. Your fraud team must verify the customer with your own procedure, and never ask for a PIN, one-time code, password or card number.
- Add people to Fraud team, Fraud leads and Customer support. A task assigned to an empty team reaches nobody, and a fraud task must never go unseen.
- Tell customers on your site that you never ask for a PIN, one-time code, password or card number by message or call.
- Connect an SMS provider or finish business verification, switch the follow-ups on and test each reason with your own phone.
- Send
Transaction Failedwithreason(insufficient_funds,network,limit,suspected_fraudorother) andchannel. The first message covers every reason that isn’t one of the other three, so a new reason such astimeoutgets the try-again text. An event with noreasonsends nothing. - Suspected fraud is deliberately quiet. The SMS says only that you paused a transaction and asks the customer to call the number on their card or in the app. Never put a reason, merchant, amount or account number in it: fraudsters read SMS too, and shared phones are common.
- The repeated-failure rule counts events over the last day, so it needs the event history to be complete. A person can match both a reason message and the repeated-failure task; that is intended.
- Reversal times differ: card and bank-transfer reversals can take longer than wallets. In Nigeria, many failed transfers show as “pending” first, so say what your customers will see in the app. Change the hour count to match.
This playbook is synthesized: no customer has run it with us yet. If you build it, tell us what you changed, and we’ll replace it with the real version.
Copilot eval
Section titled “Copilot eval”The request used to test the copilot on this playbook (a live eval):
Our app sends a Transaction Failed event with a reason (insufficient_funds, network, limit, suspected_fraud or other). For network or other failures, text the customer that they should try again and that any debit is reversed within 24 hours. For limit failures, text how to raise their limit. For suspected fraud, don't put any detail in a message: just text them to call us and give our fraud team a task due within an hour. If someone has two failed transactions in a day, give support a task. Never show amounts or account numbers and never ask for PINs or OTPs.
It passes when every piece is a valid draft and everything lands off, with at least: segment, workflow, message_template.