How to stop duplicate payment callbacks from double-crediting orders (Indonesia QRIS & virtual accounts)

William Beaumont — Tue, 10 Nov 2026 19:17:00 +0000

A customer pays, the order becomes paid, and your webhook endpoint loses its connection before the acknowledgement reaches the provider. The provider sends the notification again. Nothing unusual has happened to the payment, but your application now has another opportunity to credit the customer.

This is the failure sequence I would start with when reviewing a QRIS or virtual account integration. It is a hypothetical example, not a reported production incident. Its value is that every component can behave reasonably while the combined system still produces a duplicate credit.

The design question is simple: which durable record prevents a second delivery from causing a second business effect?

Separate the delivery from the payment

A webhook delivery is a message about a payment. It is not itself a new payment, and its arrival time does not establish the order of payment events.

Keep separate identifiers for the merchant order, provider transaction, and notification event where available. Scope provider identifiers to the integration and merchant account unless the documented contract guarantees a wider uniqueness scope.

An event identifier helps detect repeated messages. A provider transaction reference helps identify the money movement. An order identifier ties that movement to your business obligation. These keys answer different questions; replacing them all with one orderId makes reconciliation harder.

For QRIS and virtual accounts, also confirm how the approved integration maps instructions to orders. Do not assume that a QR instruction is reusable or that a virtual account identifies exactly one invoice. A reusable account number alone is an unsafe deduplication key.

Put the invariant in the database

The invariant for a single-payment order is: one accepted payment can create at most one order credit. For split payments or other models, define a different explicit invariant before writing the handler.

A memory cache cannot enforce this across restarts and multiple workers. A database query followed by an unconditional insert also leaves a race: two workers can both observe that no credit exists.

Use database constraints and a transaction around the business mutation. A useful minimal design includes a webhook inbox, a payment allocation record, an order credit ledger, and an outbox for downstream fulfilment. Give each its own uniqueness rule. The inbox can have a unique event key; the order credit should have a unique business key such as (order_id, credit_kind).

The payment allocation also needs a constraint preventing the same scoped provider transaction from being assigned to two orders. Otherwise, order-level protection can still allow one payment to fund two purchases.

Authenticate first, then commit the decision

Verify the provider's documented webhook authentication before trusting the payload. Preserve raw request bytes if signature verification requires them. Validate the merchant account, order mapping, amount, currency, and payment status against your records.

Do not invent a universal signature header, success status, or acknowledgement body. Those are integration contracts. The following Node-style pseudocode deliberately hides them behind adapter functions:

async function webhook(req, res) {
  const event = adapter.verifyAndNormalize(req.rawBody, req.headers);
  // Adapter rejects unauthenticated or malformed input.

  await db.transaction(async (tx) => {
    const fresh = await tx.inbox.insertIfAbsent(event);
    // Uses a stable, scoped event ID if the contract provides one.
    if (!fresh) return;

    const order = await tx.orders.lockForUpdate(event.orderId);
    const decision = validatePaymentForOrder(event, order);
    if (!decision.accepted) {
      await tx.exceptions.record(event, decision.reason);
      return;
    }

    if (order.creditPosted) {
      // Different payment references need review, not another credit.
      await tx.payments.recordObservation(event, order);
      return;
    }

    await tx.allocations.claimUniquePayment(event, order.id);
    await tx.ledger.insertUniqueOrderCredit(order, event);
    await tx.orders.markPaid(order.id, event.paymentRef);
    await tx.outbox.insertUnique({
      key: `fulfil:${order.id}`,
      type: "FULFIL_ORDER",
      orderId: order.id
    });
  });

  adapter.sendDocumentedAcknowledgement(res);
}

These helpers imply actual SQL constraints, row locking, and conflict handling, not merely application checks. validatePaymentForOrder must reject ineligible states and unverified success claims. An allocation conflict must roll back the transaction and enter a durable investigation path; it must never fall through to a credit.

When no stable event ID exists, store delivery observations without pretending a generated local ID detects duplicates. Payment allocation and order credit constraints remain the business protection. A payload hash alone is not a reliable payment identity.

Acknowledgement is a durability boundary

Return the documented acknowledgement once the event and its disposition are durable. An authenticated amount mismatch can be recorded for investigation without accepting it as a valid credit. Invalid authentication should follow the integration's rejection procedure.

If the transaction fails, do not send a success acknowledgement claiming the work was stored. Use the provider's documented error behavior and your recovery process. Conversely, if the commit succeeds and the response disappears, the next delivery should find durable evidence and receive the normal acknowledgement without another credit.

Keep slow fulfilment outside the webhook transaction. The outbox closes the gap between committing the order and scheduling that work. Its consumer still needs idempotency: a worker can perform an action and crash before recording completion. Pass the stable fulfilment key to an idempotent downstream operation, or provide a recovery procedure for uncertain side effects.

Do not erase a second real payment

Two callbacks with the same transaction reference may describe one payment. Two distinct transaction references for one order may describe two payments. Suppressing both as “already paid” would hide money that finance needs to account for.

Record the additional payment observation and reconcile it through the approved query or reporting process. An extra payment does not authorize another fulfilment, and it should not trigger an automatic refund based only on an unfamiliar callback.

Similarly, an old pending notification must not downgrade a verified paid order. Refunds and reversals belong to explicit lifecycle transitions with their own ledger adjustments. A status field that accepts whichever message arrived last is not a payment state machine.

Test the spaces between successful steps

I would make the test harness pause at the commit boundary, then kill the connection before the acknowledgement. Replay the same verified event and inspect the ledger, order, outbox, and acknowledgement together.

Also send concurrent deliveries to separate workers. Deliver two different event IDs for the same transaction. Send an older pending event after success. Try a second transaction for the same order, an amount mismatch, and a reused transaction reference against another order.

The expected result is more precise than “the endpoint returned success”: one valid order credit, one intended fulfilment, preserved evidence for exceptions, and no silent state regression.

Finally, make missing callbacks recoverable. A reconciliation job should compare provider records with local payments and orders, then route verified differences through the same guarded transition logic. Separate provider-pending payments, missing notifications, and failures to apply a received notification in operational views. They require different investigations.

A useful support record contains scoped references, amount, currency, event and receipt timestamps, verification outcome, and processing disposition. Keep secrets and full customer banking details out of ordinary logs.

For a compact checklist to use during implementation review, PAYJN's guide to handling duplicate payment webhook events covers acknowledgement, order credit protection, and conflicting notifications.