# Checklist de produção (/docs/pix-processamento/best-practices/checklist)



<QuickLinks>
  <QuickLink href="/docs/pix-processamento/best-practices/idempotency" title="Idempotência" />

  <QuickLink href="/docs/pix-processamento/best-practices/callbacks" title="Callbacks" />

  <QuickLink href="/docs/pix-processamento/best-practices/errors" title="Tratamento de erros" />

  <QuickLink href="/docs/pix-processamento/best-practices/security" title="Segurança" />
</QuickLinks>

Marque tudo antes de subir produção. Cada item linka para a seção correspondente.

## Idempotência [#idempotência]

| Item                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------- |
| `clientReference` único e determinístico em toda criação. Ver [Idempotência](/docs/pix-processamento/best-practices/idempotency). |
| Dedupe de callback por `id + status`, não só `id`.                                                                                |
| Storage de dedupe persistente (Redis/DB), não em memória local.                                                                   |
| TTL do dedupe ≥ 30 dias.                                                                                                          |

## Callbacks [#callbacks]

| Item                                                                                        |
| ------------------------------------------------------------------------------------------- |
| `callbackUrl` configurado em todo `POST /pix`, `POST /withdraw`, `POST /internal-transfer`. |
| Handler responde `2xx` em menos de 5s. Processamento pesado em fila/worker.                 |
| Testado com payload simulado via curl + ngrok.                                              |
| Endpoint restringido ao IP oficial da PayZu (peça ao suporte).                              |
| Inspeção via `GET /user/callbacks` configurada para auditoria.                              |

## Multi-tenant (se aplicável) [#multi-tenant-se-aplicável]

| Item                                                                                   |
| -------------------------------------------------------------------------------------- |
| `virtualAccount` enviado em todas as criações.                                         |
| Listagem filtrada por `virtualAccount`.                                                |
| Roteamento do callback usa `tx.virtualAccount`, com fallback para tenant desconhecido. |
| Onboarding de novo tenant não exige deploy (mapping em DB ou config dinâmica).         |

## Dinheiro [#dinheiro]

| Item                                                                            |
| ------------------------------------------------------------------------------- |
| Valores armazenados como inteiro em centavos ou `NUMERIC(15,2)`, nunca `FLOAT`. |
| Conversão centavos ↔ reais isolada em helper, testada.                          |
| Validação no callback: valor recebido bate com valor esperado do pedido.        |
| Tarifa (`serviceFeeCharged`) contabilizada na conciliação.                      |
| Limites mínimos respeitados (cobrança ≥ R$ 1, saque ≥ R$ 0,01, QR ≥ R$ 0,10).   |

## Segurança [#segurança]

| Item                                                                                  |
| ------------------------------------------------------------------------------------- |
| Token em Secret Manager, não em `.env` versionado.                                    |
| Token nunca exposto ao front-end.                                                     |
| Logger mascara header `Authorization` e campos sensíveis (`payerDocument`, `pixKey`). |
| Tokens separados para sandbox e produção.                                             |
| Plano de rotação documentado (quando, quem, como).                                    |
| DICT consultado antes de saque por chave em valores altos.                            |

## Tratamento de erros [#tratamento-de-erros]

| Item                                                                 |
| -------------------------------------------------------------------- |
| Retry só em `5xx`, `429` e `424`, com backoff exponencial e jitter.  |
| **Não** retentar `4xx` (exceto `424` e `429`).                       |
| Timeout tratado com consulta por `clientReference` antes de recriar. |
| `requestId` da PayZu logado em todo erro.                            |
| Erros traduzidos pro usuário final (não expõe `message` cru).        |

## Paginação e conciliação [#paginação-e-conciliação]

| Item                                                                                     |
| ---------------------------------------------------------------------------------------- |
| Iteração de listagem usa `hasNextPage`, não `data.length`.                               |
| `limit` ≤ 100.                                                                           |
| Job diário de conciliação cruzando `GET /user/transactions` com tabela de pedidos local. |
| Para volumes grandes, `POST /user/report` agendado.                                      |
| Divergências de status disparam alerta.                                                  |

## Observabilidade [#observabilidade]

| Item                                                                               |
| ---------------------------------------------------------------------------------- |
| Logs estruturados com `id` local + `id` PayZu + `endToEndId` + `clientReference`.  |
| Métricas: taxa de sucesso de criação, latência p95, erros por tipo.                |
| Alertas: erro 5xx e 424 > X% em janela curta, callback não processado > N minutos. |
| Trace distribuído (OpenTelemetry) propagando `requestId` da PayZu.                 |

## Ambiente [#ambiente]

| Item                                                               |
| ------------------------------------------------------------------ |
| Sandbox usado em desenvolvimento e testes.                         |
| Produção só com valores e clientes reais.                          |
| Variáveis de ambiente separadas (`PAYZU_TOKEN`, `PAYZU_BASE_URL`). |
| Webhook em produção via URL estável (não túnel temporário).        |

## Operacional [#operacional]

| Item                                                                                             |
| ------------------------------------------------------------------------------------------------ |
| Runbook para incidente: callback parou de chegar, erro 5xx ou 424 persistente, saldo divergente. |
| Contato direto com suporte PayZu (canal, SLA).                                                   |
| Procedimento de reenvio de callback documentado (`POST /user/callbacks/resend`).                 |
| Plano de rollback de feature que toque saque ou transferência.                                   |