# Glossário (/docs/pix-processamento/glossary)
## Conceitos gerais [#conceitos-gerais]
| Termo | Definição |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Pix** | Sistema de pagamentos instantâneos do Banco Central do Brasil. Funciona 24/7, liquidação em segundos. |
| **DICT** | Diretório de Identificadores de Contas Transacionais. Base do Bacen que mapeia chave Pix → conta. Consulte antes de pagar. |
| **EMV / BR Code** | Padrão internacional usado pelo Pix para gerar QR Codes copia-e-cola. Strings que começam com `00020126...`. |
| **QR dinâmico** | QR Code com `id` e (opcionalmente) valor por cobrança. |
| **QR estático** | QR Code reaproveitável, o mesmo código para vários pagamentos. |
| **MED** | Mecanismo Especial de Devolução. Processo do Bacen para contestar Pix em caso de fraude ou erro. Vira **infração** na PayZu. |
| **Bearer token** | Token de autenticação enviado no header `Authorization: Bearer SEU_TOKEN`. Único método de auth da PayZu. |
| **Callback / Webhook** | `POST` que a PayZu envia para sua `callbackUrl` quando uma transação muda de status. Retry até 72 tentativas com backoff. |
| **Idempotência** | Garantia de que executar a mesma operação várias vezes tem o mesmo efeito que executar uma. Use `clientReference` na criação. |
| **Backoff exponencial** | Estratégia de retry onde o intervalo entre tentativas dobra (1s, 2s, 4s, 8s). Usado pela PayZu e recomendado no seu retry em `5xx`/`429`. |
| **Jitter** | Variação aleatória adicionada ao backoff para evitar "thundering herd" (clientes batendo todos juntos). |
## Tipos de transação (`type`) [#tipos-de-transação-type]
| Valor | O que é |
| ------------ | ------------------------------------------------------------------------------ |
| `DEPOSIT` | Cobrança Pix, dinheiro entrando na sua conta. |
| `WITHDRAW` | Saque Pix, dinheiro saindo para uma chave Pix ou QR Code. |
| `COMMISSION` | Lançamento de comissão (uso interno). Pode aparecer em listagens e relatórios. |
## Método da transação (`method`) [#método-da-transação-method]
| Valor | O que é |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `PIX` | Operação liquidada via Pix. |
| `BANK_SLIP` | Operação via boleto. |
| `INTERNAL_TRANSFER` | Transferência entre contas PayZu, instantânea. Cada perna chega com `type` `WITHDRAW` (pagador) ou `DEPOSIT` (recebedor). |
## Status de transação (`status`) [#status-de-transação-status]
O status varia por tipo. Lista completa:
| Status | Significado |
| -------------------- | --------------------------------------------------------------------------- |
| `PENDING` | Aguardando pagamento (cobrança) ou processamento (saque/transferência). |
| `COMPLETED` | Concluída com sucesso. Em depósito: cliente pagou. Em saque: dinheiro saiu. |
| `CANCELED` | Cancelada antes de concluir (manual ou por regra). |
| `WAITING_FOR_REFUND` | Aguardando processamento de estorno (geralmente após MED aceito). |
| `REFUNDED` | Estornada, valor devolvido ao pagador. |
| `EXPIRED` | Cobrança expirou sem pagamento (passou de `expiresIn`). |
| `ERROR` | Erro técnico durante a operação. Veja `cancellationReason` no payload. |
## Status de estorno (`refundStatus`) [#status-de-estorno-refundstatus]
| Valor | Significado |
| ----------- | ------------------------------------ |
| `PENDING` | Estorno em fila de processamento. |
| `COMPLETED` | Estorno processado, valor devolvido. |
| `CANCELED` | Estorno cancelado antes de concluir. |
## Tipos de chave Pix (`pixType`) [#tipos-de-chave-pix-pixtype]
Os cinco tipos de chave (`cpf`, `cnpj`, `phone`, `email`, `evp`), com formato e exemplo de cada um, estão em [Tipos de chave Pix](/docs/pix-processamento/pix-key-types).
## Infração / MED [#infração--med]
### Status (`infraction.status`) [#status-infractionstatus]
| Valor | Descrição |
| --------------------- | ---------------------------------------------------- |
| `WAITING_PSP` | Aguardando resposta do provedor. |
| `OPEN` | Infração ativa e em análise. |
| `ACKNOWLEDGED` | Reconhecida pela instituição. |
| `DEFENDED` | Defesa foi submetida. |
| `ANSWERED` | Informações adicionais fornecidas. |
| `WAITING_ADJUSTMENTS` | Aguardando documentação. |
| `CLOSED` | Resolvida com decisão final (veja `analysisResult`). |
| `CANCELLED` | Cancelada antes da resolução. |
### Tipo (`infraction.type`) [#tipo-infractiontype]
| Valor | Descrição |
| ------------------ | ----------------------------------- |
| `REFUND_REQUEST` | Pedido de estorno padrão. |
| `FRAUD` | Reclamação relacionada à segurança. |
| `REFUND_CANCELLED` | Cancelamento de estorno anterior. |
### Resultado da análise (`infraction.analysisResult`) [#resultado-da-análise-infractionanalysisresult]
| Valor | Descrição |
| ----------- | --------------------------------------------------- |
| `AGREED` | Infração aceita. Estorno será processado. |
| `DISAGREED` | Infração rejeitada. Sem estorno, transação mantida. |
### Quem reportou (`infraction.reportedBy`) [#quem-reportou-infractionreportedby]
| Valor | Descrição |
| ---------------------- | ------------------------------- |
| `DEBITED_PARTICIPANT` | Instituição do pagador abriu. |
| `CREDITED_PARTICIPANT` | Instituição do recebedor abriu. |
## Campos comuns da API [#campos-comuns-da-api]
Mantemos o nome em inglês porque é como vão no JSON.
### Identificação [#identificação]
| Campo | Para que serve |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Identificador único da transação na PayZu. Formato `PAYZU` + timestamp + hash. |
| `clientReference` | Identificador externo que **você** define. Volta em todo callback. Máximo 64 caracteres. |
| `virtualAccount` | Subconta virtual (até 50 chars) para multi-tenant (lojas, filiais, marketplaces). Volta no callback. |
| `endToEndId` | Identificador único da operação no Bacen. Formato `E` + 32 caracteres. Útil em disputas. |
| `requestId` | **ID único da chamada na PayZu**. Aparece em **toda resposta de erro** (4xx e 5xx). Sempre logue e envie ao abrir suporte, investigação rastreia direto. Ver [Formato de erro](/docs/pix-processamento/authentication#formato-de-erro). |
| `accountNumber` | Número da conta PayZu (6 dígitos). Identifica a conta em transferências internas e no payload de transações. |
### Valores [#valores]
| Campo | Para que serve |
| ------------------- | ------------------------------------------------------ |
| `amount` | Valor em **reais (BRL)**. Ex: `10.90` é R$ 10,90. |
| `serviceFeeCharged` | Tarifa cobrada pela PayZu sobre a operação, em reais. |
### Cobrança gerada [#cobrança-gerada]
| Campo | Para que serve |
| ------------------- | ------------------------------------------------------------------------ |
| `qrCodeText` | Código Pix copia-e-cola (EMV BR Code). Use em input com botão de copiar. |
| `qrCodeUrl` | URL pública que renderiza o QR como PNG. Use direto em `![]()
`. |
| `qrCodeBase64` | Imagem do QR Code em Base64. |
| `generatedName` | Nome de referência associado à cobrança. |
| `generatedDocument` | CPF ou CNPJ associado à cobrança. |
| `generatedEmail` | Email vinculado à cobrança. |
| `expiresIn` | Tempo de expiração da cobrança em segundos. Máximo 172000 (47h). |
### Pagador [#pagador]
| Campo | Para que serve |
| ---------------------- | ------------------------------------------------------------- |
| `payerName` | Nome do pagador (vem no callback após pagamento). |
| `payerDocument` | CPF/CNPJ do pagador. |
| `payerInstitutionIspb` | ISPB do banco do pagador (8 dígitos). |
| `payerInstitutionName` | Nome do banco do pagador. |
| `payerAccountNumber` | Conta PayZu do pagador (em saques e transferências internas). |
### Recebedor [#recebedor]
| Campo | Para que serve |
| ------------------------- | --------------------------------------------------------------------- |
| `receiverName` | Nome do destinatário (em saques). |
| `receiverDocument` | CPF/CNPJ do destinatário. |
| `receiverInstitutionIspb` | ISPB do banco do destinatário. |
| `receiverInstitutionName` | Nome do banco do destinatário. |
| `receiverAccountNumber` | Conta PayZu do destinatário (em depósitos e transferências internas). |
### Saque por chave [#saque-por-chave]
| Campo | Para que serve |
| ----------------- | -------------------------------------------------------- |
| `pixKey` | Chave Pix do destinatário. Formato depende do `pixType`. |
| `pixType` | Tipo da chave: `cpf`, `cnpj`, `phone`, `email`, `evp`. |
| `withdrawPixKey` | Chave usada no saque (no callback). |
| `withdrawPixType` | Tipo da chave usada no saque. |
### Liquidação e estorno [#liquidação-e-estorno]
| Campo | Para que serve |
| -------------------- | ------------------------------------------------------------- |
| `paidAt` | Timestamp do pagamento (ISO 8601). Presente após `COMPLETED`. |
| `cancellationReason` | Motivo do cancelamento. |
| `refundEndToEndId` | EndToEnd ID do estorno. |
| `refundAmount` | Valor estornado. |
| `refundStatus` | Status do estorno: `PENDING`, `COMPLETED`, `CANCELED`. |
| `refundReason` | Motivo do estorno. |
| `refundDescription` | Descrição do estorno. |
| `refundedAt` | Timestamp do estorno (ISO 8601). |
### Outros [#outros]
| Campo | Para que serve |
| ------------- | --------------------------------------------------------------------------- |
| `callbackUrl` | URL onde a PayZu posta atualizações da transação. |
| `description` | Texto livre de até 140 caracteres (usado em saque e transferência interna). |
| `createdAt` | Timestamp de criação da transação (ISO 8601). |
| `updatedAt` | Última atualização (ISO 8601). |
| `infraction` | Objeto presente no callback quando a transação vira disputa MED. |
## Códigos HTTP [#códigos-http]
A lista completa de códigos HTTP e como reagir a cada um está em [Códigos de erro](/docs/pix-processamento/error-codes).
## Siglas adicionais (Bacen / Pix) [#siglas-adicionais-bacen--pix]
| Sigla | Expansão |
| --------- | ----------------------------------------------------------------------------------------------- |
| **Bacen** | Banco Central do Brasil. |
| **PSP** | Provedor de Serviços de Pagamento. Cada banco/fintech é um PSP. |
| **ISPB** | Identificador do Sistema de Pagamentos Brasileiro. Código de 8 dígitos que identifica cada PSP. |
| **SPI** | Sistema de Pagamentos Instantâneos. A infra do Bacen que processa o Pix. |
| **CACC** | Conta corrente (nomenclatura ISO 20022 usada pelo Bacen). |
| **SVGS** | Conta poupança. |
| **TRAN** | Conta de pagamento (transitória). |
| **CUID** | Identificador único de string usado pela PayZu em recursos internos (ex: `id` de infração). |
## Próximos passos [#próximos-passos]