# Production checklist (/en/docs/pix-processamento/best-practices/checklist)

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

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks" />

  <QuickLink href="/docs/pix-processamento/best-practices/errors" title="Error handling" />

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

Check everything before going to production. Each item links to the corresponding section.

## Idempotency [#idempotency]

| Item                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------ |
| Unique and deterministic `clientReference` on every creation. See [Idempotency](/docs/pix-processamento/best-practices/idempotency). |
| Callback dedupe by `id` plus the event, not just `id`.                                                                               |
| Persistent dedupe storage (Redis/DB), not in local memory.                                                                           |
| Dedupe TTL ≥ 30 days.                                                                                                                |

## Callbacks [#callbacks]

| Item                                                                                        |
| ------------------------------------------------------------------------------------------- |
| `callbackUrl` configured on every `POST /pix`, `POST /withdraw`, `POST /internal-transfer`. |
| Handler responds `2xx` in under 5s. Heavy processing in queue/worker.                       |
| Tested with simulated payload via curl + ngrok.                                             |
| Endpoint restricted to PayZu's official IP (ask support).                                   |
| Inspection via `GET /user/callbacks` configured for auditing.                               |

## Multi-tenant (if applicable) [#multi-tenant-if-applicable]

| Item                                                                             |
| -------------------------------------------------------------------------------- |
| `virtualAccount` sent in all creations.                                          |
| Listing filtered by `virtualAccount`.                                            |
| Callback routing uses `tx.virtualAccount`, with fallback for unknown tenant.     |
| New tenant onboarding does not require deploy (mapping in DB or dynamic config). |

## Money [#money]

| Item                                                                           |
| ------------------------------------------------------------------------------ |
| Amounts stored as integer in cents or `NUMERIC(15,2)`, never `FLOAT`.          |
| Cents ↔ reais conversion isolated in a helper, tested.                         |
| Callback validation: received amount matches expected order amount.            |
| Fee (`serviceFeeCharged`) accounted for in reconciliation.                     |
| Minimum limits respected (charge ≥ R$ 1, Pix payment ≥ R$ 0.01, QR ≥ R$ 0.10). |

## Security [#security]

| Item                                                                                  |
| ------------------------------------------------------------------------------------- |
| Token in Secret Manager, not in versioned `.env`.                                     |
| Token never exposed to the front-end.                                                 |
| Logger masks `Authorization` header and sensitive fields (`payerDocument`, `pixKey`). |
| Separate tokens for sandbox and production.                                           |
| Documented rotation plan (when, who, how).                                            |
| DICT queried before a Pix payment by key on high amounts.                             |

## Error handling [#error-handling]

| Item                                                                       |
| -------------------------------------------------------------------------- |
| Retry only on `5xx`, `429` and `424`, with exponential backoff and jitter. |
| `4xx` (except `429` and `424`) **not** retried.                            |
| Timeout handled by querying via `clientReference` before recreating.       |
| PayZu's `requestId` logged on every error.                                 |
| Errors translated for the end user (does not expose raw `message`).        |

## Pagination and reconciliation [#pagination-and-reconciliation]

| Item                                                                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Listing iteration uses the route's stop condition: `pages` on transactions, `pagination.hasNextPage` on callbacks, `pagination.totalPages` on infractions. |
| `limit` within the route maximum: 1000 on `/user/transactions`, 100 on the others.                                                                         |
| Daily reconciliation job cross-checking `GET /user/transactions` with local orders table.                                                                  |
| For large volumes, scheduled `POST /user/report`.                                                                                                          |
| Status divergences trigger an alert.                                                                                                                       |

## Observability [#observability]

| Item                                                                                 |
| ------------------------------------------------------------------------------------ |
| Structured logs with local `id` + PayZu `id` + `endToEndId` + `clientReference`.     |
| Metrics: creation success rate, p95 latency, errors by type.                         |
| Alerts: 5xx and 424 errors > X% in short window, callback not processed > N minutes. |
| Distributed tracing (OpenTelemetry) propagating PayZu's `requestId`.                 |

## Environment [#environment]

| Item                                                              |
| ----------------------------------------------------------------- |
| Sandbox used in development and testing.                          |
| Production only with real values and customers.                   |
| Separate environment variables (`PAYZU_TOKEN`, `PAYZU_BASE_URL`). |
| Webhook in production via stable URL (not temporary tunnel).      |

## Operational [#operational]

| Item                                                                                         |
| -------------------------------------------------------------------------------------------- |
| Incident runbook: callback stopped arriving, persistent 5xx or 424 error, divergent balance. |
| Direct contact with PayZu support (channel, SLA).                                            |
| Documented callback resend procedure (`POST /user/callbacks/resend`).                        |
| Rollback plan for features touching Pix payment or transfer.                                 |