8. Checklist de go-live

Segurança

• Chave SECRET só no servidor, em cofre de segredos; nunca em app, navegador ou repositório.
• Cada chave com só os scopes que usa.
• Assinatura de todo webhook validada com o corpo cru e o signingSecret (Assinatura).
• URL do webhook em HTTPS público.

Idempotência

Operação	Como	Regra
Cobrança Pix	idempotencyKey no corpo	Use o id do pedido. Reenvio devolve a mesma cobrança.
Saque Pix	idempotencyKey no corpo	Use o id do saque no seu sistema.
Reembolso	header Idempotency-Key	Uma chave por reembolso.
Pagar cliente / sacar saldo cripto	header Idempotency-Key	Mesma chave + mesmo corpo = mesmo saque; corpo diferente = 409 idempotency_conflict.

• Em timeout ou 5xx, repita com a mesma chave. Só gere chave nova para uma operação nova.
• Depois de FAILED, uma nova tentativa é uma operação nova: chave nova.

Webhooks

• Responde 2xx em até 5 segundos e processa em fila.
• Idempotente: o mesmo evento pode chegar mais de uma vez. Deduplique por id do recurso + event (subTransactionId, withdrawId, refundId, depositId, payoutId, withdrawalId, customerId).
• Não depende da ordem de chegada: confira o status atual antes de mudar o seu.
• Inscrito em todos os eventos dos fluxos que você usa (Eventos).

Reconciliação por consulta

O webhook é a fonte principal; a consulta é a rede de segurança.

Recurso pendente	Consulta	Frequência sugerida
Cobrança Pix PENDING	GET /payments/merchant/transaction/:subTransactionId	Quando o cliente disser que pagou, ou a cada poucos minutos até expirar
Saque Pix	GET /withdraws/merchant/:id	A cada minuto até COMPLETED/FAILED
Cliente cripto PENDING/IN_REVIEW	GET /crypto/customers/:id	A cada algumas horas
Depósito cripto	GET /crypto/deposits?from=…	Diariamente, para conciliar
Pagamento/saque cripto PROCESSING	GET /crypto/payouts/:id, GET /crypto/withdrawals/:id	A cada minuto

• Rotina diária comparando os seus registros com as listagens (/merchant/transactions, /withdraws/merchant, /crypto/deposits, /crypto/withdrawals).

Erros que o seu código precisa tratar

HTTP	Significado	Ação
400	Corpo ou header inválido	Corrigir; não repetir igual.
401	Chave inválida	Alarme: credencial errada ou revogada.
403	Sem scope, cripto desligado ou cliente sem KYC (kyc_required)	Corrigir configuração ou aguardar o cliente.
404	Recurso não existe na sua empresa	Conferir o id.
409	Conflito de estado (idempotency_conflict, identity_mismatch, merchant_not_ready, merchant_wallet_not_ready)	Ler o error e agir; não repetir às cegas.
422	Regra de negócio (insufficient_balance, limit_exceeded, amount_below_minimum, provider_cost_exceeds_fee, pix_key_not_owned…)	Mostrar ao usuário ou ajustar o valor. Nada foi reservado.
429	Rate limit	Esperar e repetir com backoff (Erros e rate limit).
503	Provedor ou cotação indisponível	Repetir com backoff e a mesma chave de idempotência.

Testes antes de abrir para clientes

• Cobrança Pix paga de ponta a ponta, com transaction.paid recebido e validado.
• Reembolso parcial com transaction.refunded.
• Saque Pix com withdraw.completed.
• Cripto: cliente de teste aprovado, depósito com crypto.deposit.paid, pagamento de R$ 10,00 + taxa com crypto.payout.paid e o valor conferido no extrato.
• Cripto (se for sacar o saldo da loja): cadastro cripto da loja aprovado e saque com crypto.withdrawal.paid.
• Simulação de timeout: repetir a chamada com a mesma chave não duplica a operação.