The Complete Guide to Fonepay API Integration for Developers
Fonepay's merchant API documentation covers the happy path well. This is what we've learned handling the parts it doesn't spell out, across real production integrations.
The three stages you must design for
- Initiation — generating the payment request with the correct merchant credentials and a properly signed payload
- Callback verification — validating that the callback actually originated from Fonepay and hasn't been tampered with, before trusting it
- Reconciliation — matching the callback against your own order record and handling the case where the callback arrives late, twice, or not at all
The mistake we see most often
Developers often treat the callback as the only source of truth and skip building a fallback status-check call. Networks drop callbacks. Build a scheduled job that queries Fonepay's status endpoint for any order still "pending" after a few minutes, so a dropped webhook never leaves a customer's order stuck in limbo.
Handling pending and failed states properly
Don't just show "payment failed" — distinguish between a hard decline (retry won't help) and a timeout (retry might). Customers abandon carts permanently when a temporary glitch is presented as a permanent failure.
Testing in sandbox vs production
Fonepay's sandbox environment doesn't perfectly mirror every production edge case, particularly around QR expiry timing. Budget time for a careful staged rollout with real small-value transactions before going fully live.
Security basics that are easy to skip
Always verify signatures server-side, never trust amount or status fields sent from the client, and log every callback payload for at least 90 days for dispute resolution.
We've integrated Fonepay across multiple production storefronts — see our Fonepay-integrated eCommerce build. Need a hand with your integration? Get in touch.