Using an LLM to Explain Failed Payments to Customers

// Cache for common failure explanations (same input → same output)
var explanationCache = new Map();

async function explainPaymentFailure({ gateway_response, channel, amount_ngn }) {
  var cacheKey = gateway_response + ':' + channel;
  if (explanationCache.has(cacheKey)) {
    return explanationCache.get(cacheKey);
  }

  var channelContext = {
    card: 'This was a card payment.',
    mobile_money: 'This was a mobile money payment (M-Pesa/Airtel Money).',
    bank: 'This was a bank transfer payment.',
    ussd: 'This was a USSD payment.',
  }[channel] || '';

  var prompt = `A customer's payment of NGN ${amount_ngn} failed with this bank message: "${gateway_response}". ${channelContext}

Write a brief, friendly explanation for the customer that:
1. Acknowledges the payment did not go through
2. Explains the likely cause in plain language (no technical jargon)
3. Gives 1-2 specific actions the customer can take
4. Is 2-3 sentences maximum

Do not: mention the bank's internal error message, reveal system details, or use phrases like "error code".
The customer sees this message directly.`;

  var response = await anthropic.messages.create({
    model: 'claude-haiku-4-5-20251001', // fast and cheap — this runs per failed payment
    max_tokens: 150,
    messages: [{ role: 'user', content: prompt }],
  });

  var explanation = response.content[0].text.trim();

  // Cache for 24 hours — same failure message = same explanation
  explanationCache.set(cacheKey, explanation);
  setTimeout(() => explanationCache.delete(cacheKey), 24 * 60 * 60 * 1000);

  return explanation;
}

// Example outputs for common Paystack failures:
// "Do Not Honour" → "Your bank declined this payment. This can happen if your card has a daily transaction limit or if your bank flagged the transaction as unusual. Try using a different card, or contact your bank to authorize the payment."
// "Insufficient Funds" → "Your account did not have enough funds to complete this payment. Please top up your account or use a different card and try again."
// "Invalid Card Number" → "There was an issue with the card number entered. Please double-check your card details and try again, or use a different card."

gateway_response	Likely Cause	Customer Action
Insufficient Funds	Account balance too low	Top up account or use different card
Do Not Honour	Bank declined without reason (fraud suspicion, limit, restriction)	Contact bank or use different card
Transaction Not Permitted to Cardholder	Card restricted for this transaction type	Contact bank to lift restriction or use different card
Invalid Card Number	Card number entered incorrectly	Check card number and re-enter
Expired Card	Card past expiry date	Use a different, non-expired card
Declined	Generic bank decline	Contact bank or use different payment method
Timeout	No response from bank within time limit	Try again — likely a temporary network issue

See building a payments support chatbot to embed this explanation pattern in a full support workflow.

Sign up for the McTaba newsletter