DEV Community: Gokul Krishna

Reconciling Payments, Refunds and Settlements: A Developer's Guide for Indian Gateways

Gokul Krishna — Wed, 28 Oct 2026 06:47:02 +0000

Accepting payments is the visible part of a payment integration. Reconciliation is the part finance teams care about: proving that every rupee captured, refunded and charged as fees matches what landed in the bank account.

This guide explains how settlements work with Indian gateways, which data to pull, and how to design a batch job that matches it all. The approach applies to Razorpay, Cashfree, PayU and others. Razorpay's settlement APIs are used as the concrete example.

Three ledgers that must agree

Reconciliation compares three independent records:

Your application database: orders, payments, refunds as your system understands them.
The gateway's records: captured payments, refunds, fees, tax, adjustments and the settlements that group them.
Your bank statement: the actual credits, each identified by a UTR (unique transaction reference).

Matching 1 to 2 tells you whether your app recorded every transaction correctly. Matching 2 to 3 tells you whether the money arrived.

How a settlement is built

Gateways do not send each payment to your bank individually. They batch transactions into settlements on a schedule. For Indian domestic payments, Razorpay's settlement FAQs describe a default T+2 working day cycle, where T is the capture date. Working days exclude Sundays, the second and fourth Saturdays, and bank holidays, so long weekends shift settlements.

Conceptually, each settlement amount is:

settled = captured payments
        - gateway fees
        - tax on fees
        - refunds
        +/- adjustments

Only captured payments are settled. Authorized but uncaptured payments do not appear.

Pulling settlement data

The most useful endpoint for reconciliation returns line items, not just totals. Razorpay's settlement recon API is GET /v1/settlements/recon/combined with year and month as required parameters, plus optional day, count (up to 1000) and skip for pagination.

Each record includes fields such as entity_id, type (payment, refund, transfer or adjustment), debit, credit, amount, fee, tax, settled, settlement_id, settlement_utr and order_receipt. All amounts are in paise.

import requests

URL = "https://api.razorpay.com/v1/settlements/recon/combined"

def fetch_recon(key_id, key_secret, year, month, day):
    rows, skip = [], 0
    while True:
        resp = requests.get(URL, auth=(key_id, key_secret), params={
            "year": year, "month": f"{month:02d}", "day": day,
            "count": 1000, "skip": skip,
        }, timeout=30)
        resp.raise_for_status()
        items = resp.json().get("items", [])
        rows.extend(items)
        if len(items) < 1000:
            return rows
        skip += 1000

The call uses HTTP basic authentication with your API key ID and key secret, so run it only on the server and load the credentials from a secrets store. Paginate until a page returns fewer rows than you asked for, because a busy day can easily exceed a single page.

Store these rows as is, in a staging table, before transforming them. Raw data makes later investigations much easier.

The order_receipt field is worth planning for at integration time. If you pass your internal order ID as the receipt when creating orders, every settled payment row carries a direct pointer back to your database.

Fees and GST

Gateway fees are deducted at source, and GST is charged on the fee. In Razorpay's payment entity, fee is the total charged including tax, and tax is the tax component. In the recon data, fee is the processing fee and tax is the tax on that fee.

Two practical points:

Do not hard-code a fee percentage in your reconciliation logic. Rates vary by method, card type and negotiated pricing. Read the fee from the data.
Keep fee and tax as separate columns. Finance teams typically need the tax total to tie back to the gateway's tax invoice for the period.

Your expected net for a payment is amount minus fee, where fee already includes tax. Getting that relationship wrong, by subtracting tax twice, is a common source of small, persistent mismatches.

Refunds and adjustments

Refunds appear as debit rows in settlement data, linked to the original payment through payment_id. They reduce the settlement for the period in which they are processed, not the period of the original payment.

Track refund status separately from payment status. Razorpay refunds move through pending, processed and failed, and its refund webhooks include refund.created, refund.processed, refund.failed and refund.speed_changed. A payment's refund_status of partial or full tells you how much has been reversed overall.

Adjustments are the catch-all: corrections and other manual entries, which can include dispute-related debits depending on the gateway. Never auto-match them. Route every adjustment row to a human review queue with its description.

Matching bank credits

The settlement UTR is the bridge between gateway and bank. When Razorpay transfers a settlement, it fires the settlement.processed webhook, described in the settlement webhook reference, with the settlement id, amount, fees, tax and utr.

Match on UTR first, then confirm the amount:

def match_bank_credit(stmt_line, settlements_by_utr):
    s = settlements_by_utr.get(stmt_line.utr)
    if s is None:
        return ("unmatched_bank_credit", stmt_line)
    if s.amount != stmt_line.amount_paise:
        return ("amount_mismatch", s, stmt_line)
    return ("matched", s)

Bank statement formats vary. Normalise the UTR (trim spaces, uppercase) and convert amounts to paise before comparing, so floating point rupees never enter the comparison.

Designing the batch job

A daily job works well for most businesses. A reasonable shape:

Pull recon rows for the previous few days, not just yesterday, to catch late entries.
Upsert into staging keyed by entity_id and settlement_id, so reruns are safe.
Match payment rows to your orders using order_receipt or the gateway order ID.
Match refund rows to your refund records using the refund ID.
Sum each settlement's rows and compare with the settlement amount.
Match settlements to bank credits by UTR.
Write every unmatched or mismatched item to an exceptions table with a reason code.

Run the job in IST and store timestamps in UTC. Date boundaries are a frequent cause of rows appearing in the "wrong" day.

Common mismatch causes

A payment captured in your app but not yet settled, because of the T+2 cycle or a holiday.
A refund initiated from the dashboard and never recorded in your database.
Partial settlements, where only part of the pending amount is settled in one transfer.
Transactions on hold, flagged by on_hold in recon data.
Late-authorised payments that your app recorded as failed.

Each of these resolves itself or needs a known action. The exceptions table should make the next step obvious.

Summary

Good reconciliation is mostly data hygiene: pass your own IDs to the gateway, store raw settlement rows, work in paise, keep fee and tax separate, and match bank credits by UTR. Build the job to be rerunnable, and route anything ambiguous to people rather than guessing.

Disclosure: The author works with the Razorpay team on content.

Idempotent Payment Processing: Handling Duplicate Webhooks, Retries and Race Conditions

Gokul Krishna — Wed, 21 Oct 2026 08:58:42 +0000

Payment systems fail in a particular way. The money moves correctly, but your application credits the customer twice, ships an order twice, or marks a paid order as failed. These bugs usually come from three sources: duplicate webhooks, retried API calls and concurrent code paths racing on the same order.

This article covers the patterns that prevent them. They apply to any gateway. Razorpay's documented behaviour is used as the concrete example.

Why duplicates are normal, not exceptional

Webhook delivery is at least once. Razorpay's webhook best practices are explicit about what that means in practice:

The same event can be delivered more than once, and this is expected.
Any non-2xx response is treated as a failure and retried.
If your server does not respond within 5 seconds, the delivery is marked as a timeout and sent again, even if you actually processed it.
Retries follow exponential backoff for 24 hours.
Events may arrive out of order.

So your handler must produce the same end state whether it sees an event once, three times, or after a later event has already arrived.

Layer 1: Deduplicate by event ID

Most gateways attach a unique identifier to each event. Razorpay sends it in the x-razorpay-event-id header. Record it with a unique constraint, inside the same transaction as the work it triggers:

CREATE TABLE processed_events (
  event_id    TEXT PRIMARY KEY,
  event_type  TEXT NOT NULL,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

async function handleEvent(eventId, event) {
  await db.tx(async (t) => {
    const inserted = await t.result(
      `INSERT INTO processed_events (event_id, event_type)
       VALUES ($1, $2) ON CONFLICT DO NOTHING`,
      [eventId, event.event]
    );
    if (inserted.rowCount === 0) return; // already handled
    await applyEvent(t, event);
  });
}

Do not check with a SELECT and then insert. Two deliveries arriving together can both pass the SELECT. Let the database constraint decide.

Layer 2: Make the business effect idempotent

Event-ID deduplication is necessary but not sufficient. Different events can describe the same business fact. For example, Razorpay fires both payment.captured and order.paid when a payment on an order is captured. If both handlers fulfil the order, you ship twice.

Key every side effect by the business entity, not the event:

One fulfilment per order: a unique constraint on fulfilments(order_id).
One ledger credit per payment: a unique constraint on ledger_entries(payment_id, entry_type).
One refund per refund request: your own refund request ID, stored before calling the gateway.

With these constraints in place, a duplicate that slips through still cannot create a second row.

Layer 3: Idempotent outbound calls

Retries also happen in the other direction. Your server calls the gateway, the network times out, and you do not know whether the request succeeded.

Some APIs accept an idempotency key header for this. Where an API does not, look for a field that serves the same purpose. Razorpay's create refund API accepts a receipt value, and the documented errors include "Duplicate receipt found for this refund request", so passing your own refund request ID as the receipt protects against double refunds on retry.

import requests

def refund(payment_id, request_id, amount_paise):
    resp = requests.post(
        f"https://api.razorpay.com/v1/payments/{payment_id}/refund",
        auth=(KEY_ID, KEY_SECRET),
        json={"amount": amount_paise, "receipt": request_id},
        timeout=30,
    )
    return resp.json()  # retry with the same request_id on timeout

For order creation, store the gateway order ID against your internal order the first time, and reuse it on retry rather than creating a new one.

Order and payment state machines

Orders and payments are separate entities with separate lifecycles. Conflating them is a common source of state bugs.

Razorpay's orders documentation describes order states of created, attempted and paid. An order can have several payment attempts, but only one successful payment. Payments move through created, authorized, captured, refunded and failed.

Model your own order as a state machine with allowed transitions, and apply updates only when they move forward:

const NEXT = {
  pending: ['paid', 'failed'],
  failed:  ['paid'],          // late success is possible
  paid:    ['refunded', 'partially_refunded'],
  partially_refunded: ['refunded'],
};

function canMove(from, to) {
  return (NEXT[from] || []).includes(to);
}

Note the transition from failed to paid. Razorpay documents late authorisation: if the bank does not respond in time, a payment can be marked failed and later move to authorized when the bank confirms. Razorpay polls the bank for up to 3 days, and uncaptured payments where money was debited are refunded automatically. If your state machine treats failed as terminal, you can end up with a customer who paid but never received the order.

Apply transitions with a conditional update so the database enforces them:

UPDATE orders
SET status = 'paid', payment_id = $2
WHERE id = $1 AND status IN ('pending', 'failed');

If zero rows are updated, someone else already moved the order. That is not an error; log it and return.

The callback versus webhook race

On a successful checkout, two things usually happen almost at the same time. The browser returns to your app with the payment details, and the gateway sends a webhook to your server. Either can arrive first. Sometimes the browser never returns at all, because the user closed the tab.

The fix is to route both paths through one function that is safe to run twice:

Verify the input. For Razorpay's checkout response, that means checking the payment signature; for the webhook, checking the webhook signature.
Lock or conditionally update the order row.
Apply the transition and side effects only if the order was not already paid.
Return the current state to the caller.

async function markPaid(orderId, paymentId) {
  return db.tx(async (t) => {
    const order = await t.one(
      'SELECT * FROM orders WHERE id = $1 FOR UPDATE', [orderId]);
    if (order.status === 'paid') return order;
    await t.none(
      "UPDATE orders SET status='paid', payment_id=$2 WHERE id=$1",
      [orderId, paymentId]);
    await t.none(
      'INSERT INTO fulfilments (order_id) VALUES ($1) ON CONFLICT DO NOTHING',
      [orderId]);
    return { ...order, status: 'paid' };
  });
}

Treat the browser callback as a user experience signal and the webhook (or a server-side fetch of the payment) as the authoritative one.

Respond fast, process later

Given the 5 second timeout, do minimal work in the webhook request: verify, record the event, enqueue, return 200. Run fulfilment, emails and ledger writes in a worker. The worker reuses the same idempotent functions, so a retried job is harmless.

Add a reconciliation sweep

Even with all of this, events can be missed, for example if your endpoint was down beyond the retry window. Schedule a job that finds orders stuck in pending or failed for longer than expected, fetches their payments from the gateway API, and feeds the result into the same markPaid function.

Summary

Deduplicate events with a database constraint, not a read-then-write check.
Key side effects by business IDs: order, payment, refund request.
Use idempotency keys or equivalent fields on outbound calls.
Model orders and payments separately, and allow late success.
Funnel callback, webhook and sweep through one idempotent function.

Disclosure: The author works with the Razorpay team on content.