Practical software guides
Fast payment rails still need exception handling. “Pending”, “failed”, “reversed” and “paid” must come from the provider’s supported states, not a customer screenshot or a timer in your app.
| Situation | Safe response |
|---|---|
| Browser times out | Check the original provider reference before retrying |
| Same event arrives twice | Deduplicate by event/transaction identity |
| Payment remains pending | Hold final fulfilment or use the approved risk policy |
| Refund requested | Check authority, original payment and provider refund state |
| Provider/bank totals differ | Reconcile references, fees and payout batch |
Use an idempotency key for supported provider write requests. Persist the business reference before acting on a callback, verify the callback’s authenticity and make duplicate delivery harmless. Unknown state should remain visible for review.
The Stripe idempotency documentation is a provider-specific example. It does not define Bahamas instant-payment-system behaviour. Consult the Central Bank and the actual participating provider for current local rail availability, rules and status semantics; no rollout date or universal instant-settlement claim is made here.
Keep card data and credentials out of application logs. The checkout-to-payout example covers reconciliation after a successful payment.