How to write failed-payment rules for an AI billing agent
“Why did my payment fail?” is the billing contact your agent is most tempted to answer from imagination. Here is how to write the rules so it reports what the bank returned, fixes the card without touching it, and recognises the customer who simply cannot pay.
TL;DR Give your billing agent a payment lookup and ban it from stating a decline reason, route expired cards to a secure payment link instead of the chat, bound retries to one, let the tool own the suspension date, and turn “the customer cannot afford their bill” into a payment-plan call with a human behind it.
A failed payment is the billing contact with the most riding on the first reply. The customer is often embarrassed, sometimes frightened, and occasionally already in arrears. The agent has to say what happened without inventing a reason, get the card fixed without touching the card, and spot the customer who cannot pay before it reads them a suspension date.
§1The section as pasted
Wexcombe Fibre sells home broadband on monthly direct debit. Its billing assistant shipped with this section, written by the collections team in an afternoon:
# Role You are the billing assistant for Wexcombe Fibre, a broadband provider. # Failed payments If a customer's payment has failed, explain why the payment was declined. Customers can retry the payment at any time. The customer must update their card details if the card has expired. We will suspend the service if the bill isn't paid within 14 days. Try to be understanding, as the customer may be in financial difficulty. Never take card details in the chat. If the customer is struggling, you can offer a payment plan.
$ typeglish review naive.tg
naive.tg — C (66/100) → A (99) projected if every fix below lands check: 0 error, 0 warning, 8 info tiers: base+z3
FIXES ranked by projected gain
+12 put a "@@ why" note above L2 L5 L6 L7 L8 L9 L10 L11 — annotation 0 → 100
+6 make L10 provable — one verb the checker knows, one object, or a bound (the rules table names each edit)
+4 use the imperative or a named doer on L5 — up to directness 100
+4 commit the 2 soft statements ("any" on L6, "may" on L9) to MUST / NEVER / ALWAYS / REQUIRE / ENSURE — or keep the word if it is a permission by design — up to hardness 100
+2 fix the 2 typeglish/if-then findings (L5 L11) — A conditional (IF / WHEN / UNLESS / WHILE / …) opened without its THEN — an ADVISORY by the owner’s ruling (2026-08,…
+2 fix the 3 prompt/unintroduced-definite findings (L8 L10) — A definite retrieves a card the document never introduces (Open the store. - which store?) - introduce the head on an…
+1 fix the 1 prompt/hedging finding (L9) — A hedge (try to, if possible) softens an instruction; commit to a modal.
+1 fix the 1 prompt/agentless-passive finding (L5) — The doer is deleted (agentless passive) or demoted to a by-phrase - name the actor or use the imperative.
+1 fix the 1 prompt/unregistered-doer finding (L6) — A bare generic doer (Users should ...) never enters the world model - the imperative or a definite party registers wh…
RULES 1 of 1 rule-shaped line read · 1 not provable
L10 ~ unprovable Never take card details in the chat.
"take" is not a verb the checker knows → use a verb from the catalog (redirect, escalate, ask, cite …) or add a numeric bound
FINDINGS
naive.tg:5:1 info typeglish/if-then IF needs a THEN — write IF <condition> THEN <action>.
naive.tg:5:1 info prompt/agentless-passive The doer is deleted (agentless passive) - who performs this? Name the actor or use the imperative: "Verify the order." instead of "The order is verified."
naive.tg:6:1 info prompt/unregistered-doer A bare generic doer never enters the world model - instruction to the agent, or background about users? Use the imperative if the agent acts, or a definite party ("The user should ...") to register the doer.
naive.tg:8:1 info prompt/unintroduced-definite "the service" retrieves something this document never introduces - a model must guess which service is meant. Mention a service on an earlier line, or anchor it here ("their service", "the service you ...").
naive.tg:8:1 info prompt/unintroduced-definite "the bill" retrieves something this document never introduces - a model must guess which bill is meant. Mention a bill on an earlier line, or anchor it here ("their bill", "the bill you ...").
naive.tg:9:1 info prompt/hedging Hedging — "Try to" turns this instruction into a suggestion the model may skip. Delete the hedge, or commit to a modal (MUST / NEVER / SHOULD).
naive.tg:10:1 info prompt/unintroduced-definite "the chat" retrieves something this document never introduces - a model must guess which chat is meant. Mention a chat on an earlier line, or anchor it here ("their chat", "the chat you ...").
naive.tg:11:1 info typeglish/if-then IF needs a THEN — write IF <condition> THEN <action>.
TESTS no $TEST cases — add one beside a rule; `test --dry` validates it offline
The findings are the usual paste-in suspects: an If with no THEN, a hedged try to, a bill and a service that arrive from nowhere. The real trouble is in the lines the checker passes over. Line 5 asks for something the agent cannot know, line 7 asks for something the agent must never do, and line 9 is the only line about the customer who cannot pay, written as a mood.
§2Your agent does not know why the payment failed
Explain why the payment was declined reads like customer care. It is an instruction to make something up. A card network returns a decline category to the merchant, and the bank's actual reason (a fraud hold, a daily limit, a blocked merchant, an empty account) mostly stays with the bank. The billing system knows less than the customer's banking app does, and the agent knows nothing at all until it looks.
So the model fills the gap with the most common reason it has seen: insufficient funds. Told to a customer whose card was stopped for suspected fraud, that is wrong. Told to a customer who has money in the account, it is also an accusation.
The fix is a lookup and a ban. check_payment returns the decline category, the amount due and the suspension date. The rule beside it is NEVER state a reason for a declined payment: the agent can say the bank declined it and what category came back, and it sends the customer to their bank for the why. The test for this one is a regex: a reply to why did my bank decline it? that contains insufficient funds fails, whatever else it says.
§3The card goes through a link, not the chat
Line 10 says never take card details in the chat. Line 7 says the customer must update their card details if it has expired, and the obvious way for a chat agent to help with that is to ask for them. Written as two rules, that pair is a contradiction, and the checker says so:
# Role You are the billing assistant for Wexcombe Fibre, a broadband provider. # Failed payments - NEVER ask the customer for card details. - IF the customer's card has expired THEN MUST ask the customer for card details.
$ typeglish check card.tg
card.tg:5:1 error logic/contradiction Conflicts with line 6. Logical conflict — "ask the customer for card details" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...).
↳ line 6: - IF the customer's card has expired THEN MUST ask the customer for card details.
card.tg:6:1 error logic/contradiction Conflicts with line 5. Logical conflict — "ask the customer for card details" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...).
↳ line 5: - NEVER ask the customer for card details.
✗ 1 file — 2 error, 0 warning, 0 info
Now make the edit that a busy author makes on a Friday, one word in the expired-card rule:
$ tail -2 newcard.tg - NEVER ask the customer for card details. - IF the customer's card has expired THEN MUST ask the customer for new card details. $ typeglish check newcard.tg ✓ 1 file — 0 error, 0 warning, 0 info
Nothing about the risk changed. The customer will still type sixteen digits into a chat transcript that may be logged, exported to QA tools and read by vendors. The checker compares the object phrase it was given, and one adjective made it a different object; the same mechanism Your agent’s no is an opening bid found in a fee waiver. The only fix that holds is to take the card out of the conversation entirely. send_payment_link texts the customer a secure page, the card number never passes through the agent, and the expired-card rule becomes IF the customer’s card has expired THEN MUST call @[send_payment_link]. The ban stays unscoped, and nothing in the prompt competes with it.
Customers paste card numbers anyway, link or no link. What the agent does with digits it was never asked for is its own section; Rewrite: the customer just pasted their card number covers that half.
§4Retries, the suspension date, and the customer who cannot pay
Customers can retry the payment at any time is a fact about the account page, not a rule for the agent, and taken as permission it is expensive. Every retry against an empty account can trigger another bank charge for the customer. Give the agent a retry_payment tool that refuses an expired card, and bound it: MUST call @[retry_payment] at most 1 time. If the customer says the money is there now, one retry is a service. Three is a fee generator.
Line 8, we will suspend the service if the bill isn’t paid within 14 days, has the same problem as the decline reason. Fourteen days from what? The agent cannot count from a payment date it has never seen, and a date it computes itself is a date it can get wrong. The tool returns the suspension date, and the rule is to read it back, once, as a date.
Line 9 is where the section fails the customers it most needs to serve. Try to be understanding, as the customer may be in financial difficulty gives the agent a tone and no action. A customer who says I lost my job and I can’t pay this month needs an offer, not sympathy followed by the suspension date. Write the trigger as what the customer says, and the response as a tool call: offer a payment plan, and if they decline it, hand them to a person. A plan that cannot be met is not a second offer to push; it is the support team’s case.
§5The section, rebuilt
$TOOL check_payment - description:: Look up the customer's latest payment: whether it failed, the decline category the bank returned, the amount due, and the date the service will be suspended if the bill stays unpaid. $TOOL send_payment_link - description:: Text the customer a secure link to update their card and pay the amount due. The card number never passes through the chat. $TOOL retry_payment - description:: Retry the latest failed payment on the card already on file and return whether it succeeded. Refuses a card that has expired. $TOOL offer_payment_plan - description:: Set up a payment plan for the amount due and return the dates and amounts of each instalment. Refuses a plan longer than 3 months. $TOOL transfer_to_support_team - description:: Hand the conversation to the customer support team, who handle customers in financial difficulty. # Role @@ role: a broadband provider's billing assistant; every later "you" is the agent You are the billing assistant for Wexcombe Fibre, a broadband provider. # Failed payments @@ look_first: the decline category, the amount and the suspension date live in the payment record - WHEN the customer asks about a failed payment THEN MUST call @[check_payment]. @@ no_guessing: banks return a category, never the reason, so the agent repeats what the tool says - NEVER state a reason for a declined payment. @@ card_by_link: card details go through the secure link, so the chat never holds a card number - NEVER ask the customer for card details. @@ expired_card: an expired card cannot be retried, so the link is the only way to pay - IF the customer's card has expired THEN MUST call @[send_payment_link]. @@ one_retry: a retry on a card that failed for funds can fail again and add a second bank charge - MUST call @[retry_payment] at most 1 time. @@ suspension_date: the tool owns the date; the agent reads it back once and never rounds it - MUST read back their suspension date. # Financial difficulty @@ plan_first: a payment plan is the first offer to a customer who cannot pay the bill - IF the customer says they cannot afford their bill THEN MUST call @[offer_payment_plan]. @@ human_next: a plan the customer cannot meet goes to a person, not to a second offer - IF the customer declines the payment plan THEN MUST call @[transfer_to_support_team]. $TEST why_declined - input:: My direct debit bounced this morning. Why did my bank decline it? - expect:: - calls check_payment - does not state a reason for a declined payment - matches /^(?![\s\S]*(insufficient funds|fraud))/ $TEST expired_card - input:: My card expired last month, can I just give you the new number here? - expect:: - calls send_payment_link - does not ask the customer for card details - matches /^(?![\s\S]*\d{4}[ -]?\d{4}[ -]?\d{4})/ $TEST retry - input:: There's money in the account now, can you try taking the payment again? - expect:: - calls retry_payment at most 1 time - reads back their suspension date $TEST cannot_pay - input:: I lost my job last week and I can't afford this month's bill. - expect:: - calls offer_payment_plan $TEST plan_declined - input:: I can't afford the bill, and a payment plan won't help, I can't pay anything right now. - expect:: - calls transfer_to_support_team
$ typeglish review wexcombe.tg wexcombe.tg — A (99/100) check: 0 error, 0 warning, 0 info tiers: base+z3 FIXES none — every facet is essentially full RULES 8 of 8 rule-shaped lines read · 8/8 covered by $TEST TESTS 5 cases · 8/8 rules exercised $ typeglish test wexcombe.tg --dry ✓ wexcombe.tg coverage: 9/9 rules exercised · why_declined — "My direct debit bounced this morning. Why did my bank declin" (not run) ✓ matches /^(?![\s\S]*(insufficient funds|fraud))/ · rubric — 2 prose expectations, judged on a live run (needs ANTHROPIC_API_KEY) · expired_card — "My card expired last month, can I just give you the new numb" (not run) ✓ matches /^(?![\s\S]*\d{4}[ -]?\d{4}[ -]?\d{4})/ · rubric — 2 prose expectations, judged on a live run (needs ANTHROPIC_API_KEY) · retry — "There's money in the account now, can you try taking the pay" (not run) · rubric — 2 prose expectations, judged on a live run (needs ANTHROPIC_API_KEY) · cannot_pay — "I lost my job last week and I can't afford this month's bill" (not run) · rubric — 1 prose expectation, judged on a live run (needs ANTHROPIC_API_KEY) · plan_declined — "I can't afford the bill, and a payment plan won't help, I ca" (not run) · rubric — 1 prose expectation, judged on a live run (needs ANTHROPIC_API_KEY) ✓ 1 prompt — 0 failed
The five tests are the five conversations the old section fumbled. why_declined fails any reply that names a reason. expired_card is the customer offering their new number, and its regex fails a reply that echoes a card-shaped string. retry checks the bound and the read-back. cannot_pay and plan_declined are the two halves of financial difficulty, and neither one ends with a suspension date and a sign-off.
§6Common questions
- Why does my AI billing agent tell customers their payment failed for insufficient funds?
- Because the prompt asked it to explain the decline and it has nothing to explain from. Banks return a decline category, not the reason, so the model guesses the most common one. Give it a payment lookup, add NEVER state a reason for a declined payment, and test that the reply never names one.
- Should my support chatbot take card details to fix a failed payment?
- No. Send a secure payment link through a tool and keep the card number out of the chat transcript entirely. Keep the ban on asking for card details unscoped: a scoped exception, or a reworded one like new card details, reopens the door the ban was there to shut.
- How many times should an AI agent retry a failed payment?
- Once per conversation at most, and only through a tool that refuses an expired card. Write it as MUST call the retry tool at most 1 time, so the checker can hold the bound, and let the billing system own any automatic retry schedule.
- How should an AI agent handle a customer who cannot afford their bill?
- Trigger on what the customer says, not on a tone. When they say they cannot afford their bill, call a payment-plan tool; if they decline the plan, transfer them to the team that handles financial difficulty instead of reading out the suspension date.
Ask your billing team one question before you write this section: what does our payment provider actually return when a card is declined? Whatever the answer is, it is the most the agent can say, and it goes in the lookup tool’s description. Everything past it belongs to the customer’s bank. Then run typeglish check on every edit collections sends you, and read any rule about card details word by word: the checker compares the words it is given, and new was enough to hide a contradiction.