Idempotência

Idempotência é a garantia de que chamar a mesma operação várias vezes tem o mesmo efeito que chamar uma vez só. Sem isso, retries viram cobranças duplicadas, baixas em dobro e estornos perdidos.

Cenários que exigem idempotência

clientReference na criação

clientReference é o identificador externo idempotente que você define ao criar uma cobrança, pagamento Pix ou transferência. A PayZu deduplica por conta + clientReference: a mesma chave só colide dentro da sua própria conta, e a transação existente é devolvida se ela já foi criada.

Como gerar

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://seusite.com.br/webhooks/payzu"
  }'

O mesmo request em outras linguagens está no tutorial Receber pagamento Pix.

Dedupe de callbacks

O mesmo callback pode chegar mais de uma vez:

• Retry de entrega, a PayZu reenvia conforme a política de retry dos webhooks.
• Mudanças sucessivas, PENDING → COMPLETED → REFUNDED, cada uma gera callback.
• Reprocessamento manual via POST /user/callbacks/resend.

A chave de dedupe não pode ser só id: você ignoraria o callback de REFUNDED porque já viu COMPLETED antes, e o estorno não daria baixa. Monte a chave conforme a origem da entrega:

• Webhook cadastrado: use id mais o cabeçalho X-Callback-Event. Três eventos (TRANSACTION_SUSPECTED_FRAUD, TRANSACTION_SUSPECTED_FRAUD_REVERSAL e INFRACTION_CHANGED) não mudam o status da transação, então id + status descartaria essas entregas como se fossem repetição.
• callbackUrl da transação: não há cabeçalho de evento, então use id + status. Quando o corpo trouxer o objeto infraction, inclua também infraction.status na chave, senão as atualizações da disputa somem.

Implementação

import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
const TTL_30_DIAS = 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_DIAS, 'NX');
  if (!isFirstTime) return;

  await processTransaction(tx);
}

Armadilhas comuns