Idempotency

Idempotency is the guarantee that calling the same operation multiple times has the same effect as calling it once. Without it, retries turn into duplicate charges, double settlements, and lost refunds.

Scenarios that require idempotency

clientReference on creation

clientReference is the idempotent external identifier that you define when creating a charge, Pix payment, or transfer. PayZu deduplicates by account + clientReference: the same key only collides within your own account, and the existing transaction is returned if it was already created.

How to generate

curl -X POST https://api.payzu.processamento.com/v1/pix \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.90,
    "clientReference": "order-1234",
    "callbackUrl": "https://yoursite.com/webhooks/payzu"
  }'

The same request in other languages is in the Receive Pix payment tutorial.

Callback dedupe

The same callback can arrive more than once:

• Delivery retry, PayZu resends according to the webhook retry policy.
• Successive changes, PENDING → COMPLETED → REFUNDED, each one triggers a callback.
• Manual reprocessing via POST /user/callbacks/resend.

The dedupe key cannot be just id: you would ignore the REFUNDED callback because you already saw COMPLETED before, and the refund would not be settled. Build the key according to where the delivery came from:

• Registered webhook: use id plus the X-Callback-Event header. Three events (TRANSACTION_SUSPECTED_FRAUD, TRANSACTION_SUSPECTED_FRAUD_REVERSAL and INFRACTION_CHANGED) do not change the transaction status, so id + status would discard those deliveries as duplicates.
• Transaction callbackUrl: there is no event header, so use id + status. When the body carries the infraction object, add infraction.status to the key as well, otherwise dispute updates disappear.

Implementation

import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
const TTL_30_DAYS = 30 * 86400;

type PayzuCallback = {
  id: string;
  type: 'DEPOSIT' | 'WITHDRAW';
  method: 'PIX' | 'BANK_SLIP' | 'INTERNAL_TRANSFER';
  status: 'PENDING' | 'COMPLETED' | 'CANCELED' | 'WAITING_FOR_REFUND' | 'REFUNDED' | 'EXPIRED' | 'ERROR';
  clientReference?: string;
};

async function handleCallback(tx: PayzuCallback) {
  const dedupeKey = `payzu:${tx.id}:${tx.status}`;
  const isFirstTime = await redis.set(dedupeKey, '1', 'EX', TTL_30_DAYS, 'NX');
  if (!isFirstTime) return;

  await processTransaction(tx);
}

Common pitfalls