The unknown state

The one that prevents double charges

Never show “failed” to a customer for a payment in unknown. A customer who reads “failed” pays again — and since EcoCash offers no automatic reversal, the second charge becomes a refund: a new transaction, a new fee, a new tax, and an angry customer in between.

What unknown means

Mobile-money networks time out, drop callbacks, and answer late — routinely, not exceptionally. When Lango asks the provider “did this payment go through?” and the network doesn’t answer, there are exactly three truths and we don’t know which one holds:

1. The customer paid, and the confirmation was lost.
2. The customer didn’t pay.
3. The customer is still deciding.

Any system that maps this situation to failed is guessing — and when it guesses wrong, the customer pays twice. Lango refuses to guess. The payment enters unknown and we chase the answer: we re-query the provider on a backoff schedule (10 seconds, 30 seconds, 2, 5, 15, 30 minutes, then hourly) until it resolves or 24 hours pass.

What you should do

• Show the customer: “We’re confirming your payment with EcoCash. You’ll get an SMS from EcoCash if it went through. Please don’t pay again.”
• Don’t retry the charge. If you retry with the same Idempotency-Key, you safely get the same payment back (good). If you retry with a new key, you’re asking to charge twice (bad).
• Wait for the webhook. When the truth arrives you’ll get payment.succeeded or payment.failed like any other payment. There is no webhook event for entering unknown — it isn’t an outcome, it’s the absence of one.

If 24 hours pass

The payment becomes unresolved and a human at Lango takes over, checking provider statements directly. Your balance is not credited for unresolved payments — money you can’t prove is money you don’t have. If the money did move, resolution credits it retroactively and you’re notified; if it didn’t, the payment is failed with a paper trail.

This is rarer than it sounds — most unknown payments resolve within the first minute — but when it happens, it’s handled in the open rather than silently absorbed.