Glossário

Referência da API Webhooks MED Tipos de chave Pix

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. Único suportado pela Saq.
QR estático	QR Code reaproveitável. Não suportado pela Saq.
MED	Mecanismo Especial de Devolução. Processo do Bacen para contestar Pix em caso de fraude ou erro. Vira infração na Saq.
Bearer token	Token de autenticação enviado no header `Authorization: Bearer SEU_TOKEN`. Único método de auth da Saq.
Callback / Webhook	`POST` que a Saq 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 Saq 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`)

Valor	O que é
`DEPOSIT`	Cobrança Pix, dinheiro entrando na sua conta.
`WITHDRAW`	Saque Pix, dinheiro saindo para uma chave Pix ou QR Code.
`INTERNAL_TRANSFER`	Transferência entre contas Saq, instantânea.
`COMMISSION`	Lançamento de comissão (uso interno). Pode aparecer em listagens e relatórios.

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`)

Valor	Significado
`PENDING`	Estorno em fila de processamento.
`COMPLETED`	Estorno processado, valor devolvido.
`CANCELED`	Estorno cancelado antes de concluir.

Tipos de chave Pix (`pixType`)

Valor	O que é
`cpf`	CPF do recebedor (11 dígitos).
`cnpj`	CNPJ do recebedor (14 dígitos).
`phone`	Telefone com DDI/DDD no formato `+5511999999999`.
`email`	Endereço de email registrado no Bacen.
`evp`	Chave aleatória (UUID gerado pelo banco).

Infração / MED

Status (`infraction.status`)

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`)

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`)

Valor	Descrição
`AGREED`	Infração aceita. Estorno será processado.
`DISAGREED`	Infração rejeitada. Sem estorno, transação mantida.

Quem reportou (`infraction.reportedBy`)

Valor	Descrição
`DEBITED_PARTICIPANT`	Instituição do pagador abriu.
`CREDITED_PARTICIPANT`	Instituição do recebedor abriu.

Campos comuns da API

Mantemos o nome em inglês porque é como vão no JSON.

Identificação

Campo	Para que serve
`id`	Identificador único da transação na Saq. Formato `SAQ` + 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 Saq. Aparece em toda resposta de erro (4xx e 5xx). Sempre logue e envie ao abrir suporte, investigação rastreia direto. Ver Formato de erro.
`accountNumber`	Número da conta Saq (6 dígitos). Usado em transferência interna.

Valores

Campo	Para que serve
`amount`	Valor em reais (BRL), não centavos. Ex: `10.90` é R$ 10,90.
`serviceFeeCharged`	Tarifa cobrada pela Saq sobre a operação, em reais.

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 `<img>`.
`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

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 Saq do pagador (presente em transferências internas).

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 Saq do destinatário (em transferências internas).

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

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

Campo	Para que serve
`callbackUrl`	URL onde a Saq 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ódigo	O que significa
`200`	Sucesso na operação.
`201`	Recurso criado (cobrança, saque, transferência).
`204`	Sucesso sem corpo de resposta.
`400`	Payload inválido. Veja `message` para detalhes.
`401`	Token ausente, inválido ou revogado.
`403`	Token válido mas sem permissão para o endpoint.
`404`	Recurso não encontrado.
`409`	Conflito (duplicado, recurso em estado inválido).
`422`	Validação semântica falhou.
`429`	Rate limit atingido. Aguarde e tente novamente com backoff.
`5xx`	Erro do servidor. Retry com backoff exponencial (`5xx` e `429` apenas).

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 Saq em recursos internos (ex: `id` de infração).

Tipos de chave Pix

Tipos de chave Pix aceitos pela API Saq, formato esperado de cada um e regras de validação.

Para IAs (LLMs)

Toda a documentação da Saq disponível em formato consumível por modelos de linguagem. Copie o conteúdo direto, baixe o dump completo, ou use as URLs específicas por página. Funciona com ChatGPT, Claude, Gemini, Cursor, Copilot, etc.