Idempotency in Paystack Payment Flows

In mathematics, an idempotent operation is one where applying it multiple times gives the same result as applying it once. Setting a value to 5 is idempotent: do it once or a hundred times, the value is still 5. Adding 1 is not idempotent: each application changes the result.

In payment systems, idempotency means that if a customer triggers a payment request multiple times (intentionally or not), they are only charged once and only receive the product or service once. This sounds obvious, but it is surprisingly hard to implement correctly because payment flows involve multiple systems (your frontend, your backend, Paystack, the bank, your database) that can each retry, timeout, or deliver results out of order.

Consider what happens without idempotency:

1. Customer clicks "Pay Now" on your checkout page.
2. Your frontend sends a request to your server to initialize a Paystack transaction.
3. The network is slow. The customer sees no response and clicks "Pay Now" again.
4. Your server receives two requests and initializes two separate transactions with two random references.
5. The customer completes payment on one checkout page. The other sits open in a browser tab.
6. A week later, the customer accidentally opens the second tab and completes that payment too.
7. You now have two successful charges for the same order.

Idempotency prevents step 4 from creating two separate transactions, and prevents step 6 from resulting in a second charge.

Duplicate charges rarely happen because of bugs in Paystack. They happen because of how the internet works and how developers handle (or do not handle) the edge cases.

Double-clicks and impatient users

The customer clicks the "Pay" button, nothing visibly happens for a second, and they click again. If your frontend sends a new API request on each click without any guard, your server processes both. Disabling the button after the first click helps, but it is not sufficient. The button can be re-enabled by a page refresh, and determined users can submit the form programmatically.

Network retries

HTTP clients, load balancers, and API gateways sometimes retry failed requests automatically. If a request to your server times out (the server processed it but the response was slow), the client retries with a new request. Your server now processes the same order twice. Some HTTP libraries retry on 5xx errors by default, which can cause the same problem.

Webhook and callback race conditions

After a successful payment, Paystack sends both a webhook to your server and a redirect to the customer's browser. These arrive at different times, and sometimes both trigger fulfillment logic. If your code grants value in both the webhook handler and the callback handler without checking whether it was already granted, the customer gets two of whatever they bought.

Server restarts and queue replays

If your server crashes while processing a webhook, Paystack will retry the webhook later. If your server already partially processed the event (updated the database but crashed before sending the response), the retry processes it again. Queue-based systems face the same problem: if a worker crashes after processing a message but before acknowledging it, the message gets re-delivered.

Paystack's built-in deduplication mechanism is the transaction reference. When you call /transaction/initialize with a reference that already exists on your account:

• If the existing transaction is still pending (not paid, not expired), Paystack returns the existing transaction data with the same authorization_url and access_code.
• If the existing transaction was already completed (paid), Paystack returns an error indicating the reference has been used.

This means a deterministic reference (one derived from your order ID, not from randomness) acts as a natural idempotency key at the Paystack level.

// Deterministic reference: same order always produces the same reference
function initializePayment(order) {
  var reference = 'order_' + order.id;

  // If this order was already initialized, Paystack returns the existing transaction
  // No duplicate is created
  return fetch('https://api.paystack.co/transaction/initialize', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: order.customerEmail,
      amount: order.amountInKobo,
      reference: reference,
    }),
  }).then(function(res) { return res.json(); });
}

The critical detail: if you generate a new random reference on every request (like 'pay_' + Math.random().toString(36).slice(2)), Paystack treats each request as a new transaction. You lose the built-in deduplication entirely. This is the single most common source of duplicate charges in Paystack integrations.

For detailed reference design patterns, see transaction reference design patterns.

The Paystack reference handles deduplication at the API level, but your application needs its own layer. If your webhook handler processes a charge.success event and your callback handler also processes the same transaction, you could grant value twice even though only one Paystack transaction exists.

The solution is a database-level check that makes fulfillment idempotent.

var db = require('./database');

async function fulfillOrder(reference, paymentData) {
  // Use a transaction with a row lock to prevent race conditions
  var client = await db.pool.connect();

  try {
    await client.query('BEGIN');

    // Lock the order row. SELECT FOR UPDATE prevents another
    // concurrent process from reading this row until we commit.
    var result = await client.query(
      'SELECT id, status FROM orders WHERE paystack_reference = $1 FOR UPDATE',
      [reference]
    );

    if (result.rows.length === 0) {
      await client.query('ROLLBACK');
      console.log('No order found for reference: ' + reference);
      return { fulfilled: false, reason: 'order_not_found' };
    }

    var order = result.rows[0];

    // If already fulfilled, skip. This is the idempotency check.
    if (order.status === 'fulfilled') {
      await client.query('ROLLBACK');
      console.log('Order already fulfilled: ' + reference);
      return { fulfilled: false, reason: 'already_fulfilled' };
    }

    // Mark as fulfilled
    await client.query(
      'UPDATE orders SET status = $1, paid_at = $2, payment_data = $3 WHERE id = $4',
      ['fulfilled', new Date(), JSON.stringify(paymentData), order.id]
    );

    await client.query('COMMIT');

    // Now do the actual fulfillment (send email, activate account, etc.)
    await deliverProduct(order.id);

    return { fulfilled: true };
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

The SELECT FOR UPDATE is the key mechanism. It acquires an exclusive lock on the row, which means if the webhook handler and the callback handler both call fulfillOrder at the same time, one of them waits until the other finishes. The second one then sees status === 'fulfilled' and skips.

Without the lock, both handlers could read status === 'pending' simultaneously, both could update to fulfilled, and both could trigger delivery. The lock serializes access to the critical section.

Your webhook handler is the most important place to implement idempotency because Paystack explicitly retries webhooks that do not receive a 200 response. A crash, a timeout, or a network blip means the same event arrives again.

var express = require('express');
var crypto = require('crypto');
var db = require('./database');
var app = express();

app.post('/webhooks/paystack', express.json(), async function(req, res) {
  // Step 1: Verify signature
  var hash = crypto
    .createHmac('sha512', process.env.PAYSTACK_SECRET_KEY)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (hash !== req.headers['x-paystack-signature']) {
    return res.status(401).send('Invalid signature');
  }

  // Step 2: Respond immediately with 200
  // This tells Paystack we received the webhook.
  // Process the event after responding to avoid timeouts.
  res.sendStatus(200);

  // Step 3: Process idempotently
  var event = req.body;

  if (event.event === 'charge.success') {
    var reference = event.data.reference;

    // Check if we already processed this event
    var existing = await db.query(
      'SELECT id FROM processed_webhooks WHERE event_id = $1',
      [String(event.data.id)]
    );

    if (existing.rows.length > 0) {
      console.log('Webhook already processed: ' + event.data.id);
      return;
    }

    // Record that we are processing this event
    try {
      await db.query(
        'INSERT INTO processed_webhooks (event_id, event_type, reference, processed_at) VALUES ($1, $2, $3, $4)',
        [String(event.data.id), event.event, reference, new Date()]
      );
    } catch (err) {
      if (err.code === '23505') {
        // Unique violation: another process already inserted this event
        console.log('Concurrent processing detected: ' + event.data.id);
        return;
      }
      throw err;
    }

    // Now fulfill the order (the fulfillOrder function is also idempotent)
    await fulfillOrder(reference, event.data);
  }
});

This handler has two layers of idempotency protection:

1. The processed_webhooks table with a unique constraint on event_id ensures the same webhook event is only processed once.
2. The fulfillOrder function (from the previous section) uses SELECT FOR UPDATE to ensure the order is only fulfilled once, even if called from both the webhook and the callback.

The processed_webhooks table is simple:

CREATE TABLE processed_webhooks (
  id SERIAL PRIMARY KEY,
  event_id VARCHAR(50) UNIQUE NOT NULL,
  event_type VARCHAR(50) NOT NULL,
  reference VARCHAR(100),
  processed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Idempotency should live on the server, but adding frontend guards reduces unnecessary API calls and improves the user experience.

// Simple button disable pattern
var payButton = document.getElementById('pay-button');
var isProcessing = false;

payButton.addEventListener('click', function() {
  if (isProcessing) return;
  isProcessing = true;
  payButton.disabled = true;
  payButton.textContent = 'Processing...';

  fetch('/api/pay', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      orderId: currentOrderId,
      amount: orderTotal,
    }),
  })
  .then(function(res) { return res.json(); })
  .then(function(data) {
    if (data.authorization_url) {
      window.location.href = data.authorization_url;
    }
  })
  .catch(function(err) {
    // Re-enable on error so the user can try again
    isProcessing = false;
    payButton.disabled = false;
    payButton.textContent = 'Pay Now';
    console.error('Payment initialization failed:', err);
  });
});

This prevents most double-click scenarios. But it is not a substitute for server-side idempotency. The button state resets on page refresh, does not persist across browser tabs, and can be bypassed with developer tools. The server-side reference check is what actually prevents duplicate charges.

Think of it as layers: the frontend guard is a courtesy (it prevents unnecessary requests), the reference is a Paystack-level guard (it prevents duplicate transactions), and the database lock is your application-level guard (it prevents duplicate fulfillment).

Idempotency bugs only show up under specific conditions: concurrent requests, retries, and race conditions. You cannot find them with normal manual testing. Here is how to test them deliberately.

Test 1: Double initialization

// Send the same initialization request twice simultaneously
var reference = 'test_idempotency_' + Date.now();

Promise.all([
  initializePayment('test@example.com', 100000, reference),
  initializePayment('test@example.com', 100000, reference),
]).then(function(results) {
  // Both should return the same authorization_url
  console.log('URL 1:', results[0].data.authorization_url);
  console.log('URL 2:', results[1].data.authorization_url);
  console.log('Same URL:', results[0].data.authorization_url === results[1].data.authorization_url);
  // Expected: true
});

Test 2: Double fulfillment

// Call fulfillOrder twice with the same reference
var reference = 'test_order_123';

Promise.all([
  fulfillOrder(reference, { amount: 100000 }),
  fulfillOrder(reference, { amount: 100000 }),
]).then(function(results) {
  // Exactly one should return { fulfilled: true }
  // The other should return { fulfilled: false, reason: 'already_fulfilled' }
  console.log('Result 1:', results[0]);
  console.log('Result 2:', results[1]);
});

Test 3: Webhook replay

Send the same webhook payload to your endpoint multiple times and verify that the order is only fulfilled once. Check your database to confirm only one entry appears in processed_webhooks for that event ID.

Run these tests in your staging environment using Paystack test keys. They are the tests that catch the bugs that ship to production at 2 AM on a Friday.

Idempotency is foundational to every payment flow. For more on reference design, see transaction reference patterns. For the complete picture of accepting payments, see the complete payment acceptance guide.

Building payment systems for the African market requires getting these fundamentals right. The McTaba Full-Stack Software and AI Engineering program covers payment integration, database design, and production engineering from the ground up.