Idempotency

Idempotency guarantees that the same operation, repeated multiple times, produces only one effect. In the context of payments, this is essential to avoid charging a customer twice when an API call is retried after a network error.

Idempotency via the Idempotency-Key header

curl https://api.wajub.com/payments \
-H "Authorization: sk_test.2a7c5e91b0d34f68" \
-H "Idempotency-Key: idem-ORDER-4172-1716912000" \
-d '{
  "amount": 5000,
  "currency": "XAF",
  "email": "buyer@example.com"
}'

If the same Idempotency-Key is sent again with the same payload within 24h, the original response is returned unchanged — no new payment is created. On POST /payments, reusing the same key with a different payload returns a 422 explaining the conflict (this payload check is not yet implemented on POST /transfers — treat keys as strictly one-shot there too).

Key generation strategies

Approach 1: Order ID + attempt number (recommended)

// Generate once, store in your DB alongside the order.
// On retry, read from the DB and reuse the same key.
const idempotencyKey = `ORDER-${orderId}-ATTEMPT-${attemptNumber}`;
// Example: ORDER-4172-ATTEMPT-1   (increment only when deliberately starting over)

This approach allows a deliberate new payment attempt (e.g. after a genuine failure and user confirmation) while still deduplicating accidental network retries.

Approach 2: Order ID only (strict single-attempt lock)

// One order = one possible payment attempt ever.
// Simple and safe — the most common pattern.
const idempotencyKey = `ORDER-${orderId}`;

Approach 3: UUID

import { v4 as uuid } from 'uuid';

const idempotencyKey = uuid();

Webhook idempotency

Webhooks can be delivered multiple times (retries). Ensure your processing is idempotent by using the delivery's event identifier after verifying the signature (see Signature Verification):

const processedEvents = new Set(); // In production: Redis or a DB table

app.post('/webhooks/wajub', (req, res) => {
const event = verifyAndParse(req); // your own signature-verification helper
res.sendStatus(200);

if (processedEvents.has(event.id)) {
console.log('Event already processed, ignored:', event.id);
return;
}
processedEvents.add(event.id);

// Business processing...
});

Transfers

The same Idempotency-Key mechanism applies to POST /transfers. The beneficiary is either an existing beneficiary's id, or an inline object:

curl https://api.wajub.com/transfers \
-H "Authorization: sk_test.2a7c5e91b0d34f68" \
-H "Idempotency-Key: idem-ORDER-4172-payout-1716912000" \
-d '{
  "amount": 15000,
  "currency": "XAF",
  "beneficiary": { "name": "Jean Dupont", "channel": "cm.mtn", "phone": "+237670000001" },
  "description": "Order #4172 payout"
}'

If you send the same Idempotency-Key in a new call, the API returns the already created transfer instead of creating a second one.