The happy path of a payment integration takes a day to build. The edge cases, like duplicate notifications, timeouts and users who close the tab at the worst moment, take the rest of the project. These are the patterns we use in Django to make payments reliable, drawn from government and commercial projects.
The typical flow
- Your app creates a Payment record (status
PENDING) with a unique reference. - The user is redirected to the gateway and pays.
- The gateway calls your callback/webhook URL server-to-server with the result.
- Separately, the user's browser is redirected back to a "return URL".
Rule #1: never mark a payment as paid based on the browser redirect. The return URL can be faked, bookmarked or never reached. Only trust the server-to-server callback, or a status query you make to the gateway yourself.
Verify every callback
Treat incoming callbacks as untrusted input:
- Verify the signature or checksum using the gateway's documented method.
- Check that the amount and currency match what you expected for that reference.
- Restrict by source IP where the gateway publishes its addresses.
- When in doubt, query the gateway's status API to confirm.
Make processing idempotent
Gateways retry callbacks when they don't get a quick 200 response, so you will receive duplicates. Processing the same callback twice must have the same effect as processing it once:
from django.db import transaction
@transaction.atomic
def mark_paid(reference: str, gateway_txn_id: str, amount):
payment = (Payment.objects
.select_for_update()
.get(reference=reference))
if payment.status == Payment.PAID:
return payment # already handled: do nothing
if payment.amount != amount:
raise AmountMismatch(reference)
payment.status = Payment.PAID
payment.gateway_txn_id = gateway_txn_id
payment.save(update_fields=["status", "gateway_txn_id"])
payment.application.on_payment_confirmed() # business logic, once
return payment
select_for_update() locks the row so two simultaneous callbacks can't both pass the "already paid?" check. A unique constraint on gateway_txn_id adds a second safety net.
Respond fast, work later
Return 200 to the gateway as soon as the payment is safely recorded. Slow follow-up work such as sending emails, generating PDFs or calling other systems should go to a background queue (Celery, RQ or Django-Q). Otherwise a slow email server can make the gateway time out and retry.
Log everything
Store every raw callback payload with a timestamp and verification result in a PaymentEvent table. When a citizen or customer says "I paid but it shows unpaid", this log answers the question in minutes instead of days.
Reconcile daily
Callbacks can be lost. Run a scheduled job that:
- finds payments stuck in
PENDINGfor more than N minutes and queries the gateway for their real status, - compares your records with the gateway's settlement report and flags differences.
Testing payment flows
Use the gateway's sandbox for integration tests. For staging environments where testers can't make real payments, a controlled tool that sends a properly formed "paid" callback lets QA test the full downstream workflow (status changes, certificates, emails) without moving money. It must never be reachable by the public.
Integrating a payment gateway, or fixing one that misbehaves? Our API integration team can help.