Glossário de pagamentos e API Pix

45 termos técnicos explicados em linguagem direta, do payload do QR Code Pix à conciliação no ledger.

API: Interface programável que permite a um sistema conversar com outro. Numa API de pagamentos, é o que permite criar cobranças e consultar vendas sem interface gráfica. API Pix
API Key: Chave secreta que identifica a loja nas chamadas de API. Deve ficar apenas no servidor e nunca em código público. API Keys
Assinatura de webhook: Cabeçalho criptográfico que prova que o evento veio mesmo do provedor. Sem validá-la, qualquer pessoa poderia simular um pagamento aprovado.
Backoff: Estratégia de espera crescente entre retentativas, para não sobrecarregar um serviço que já está com dificuldade.
Bearer: Esquema de autenticação HTTP no qual a credencial é enviada no cabeçalho Authorization, precedida da palavra Bearer.
Chave de idempotência: Identificador único enviado pelo cliente numa operação de criação. Se a mesma chave chegar de novo, o provedor devolve o resultado original em vez de criar outro recurso.
Checkout: Tela onde o cliente confirma a compra e paga. Pode ser pronto, oferecido pelo provedor, ou construído pela própria loja. Checkout Pix
Cobrança: Objeto que representa a intenção de receber um valor, com identificador próprio e ciclo de vida (pendente, aprovada, expirada, cancelada, estornada). Cobrança Pix
Conciliação: Processo de casar cada valor recebido com o pedido correspondente, garantindo que nada fique sem origem.
Copia e Cola: Versão em texto do QR Code Pix, no padrão EMV. Essencial em compras feitas no próprio celular. Pix Copia e Cola
Corpo bruto (raw body): O corpo da requisição exatamente como chegou, sem conversão. É sobre ele que a assinatura do webhook deve ser validada.
Cursor: Marcador de posição usado em paginação. Evita itens repetidos ou pulados quando a lista muda durante a leitura. Paginação
EMV: Padrão internacional de formatação usado no payload do Pix, que organiza os campos do código de pagamento.
Endpoint: Endereço específico de um recurso da API, combinando método e caminho — por exemplo, criar um pagamento Pix.
Escopo: Delimitação do que uma credencial pode acessar. Escopo por loja é o que impede uma loja de enxergar dados de outra.
Estorno: Devolução total ou parcial de um valor já recebido ao pagador.
Expiração: Prazo após o qual uma cobrança Pix deixa de aceitar pagamento e precisa ser recriada.
Gateway: Camada de software que padroniza a criação de cobranças, entrega de webhooks, histórico e conciliação sobre a infraestrutura de pagamento. Gateway Pix
HMAC: Código de autenticação de mensagem baseado em hash e em um segredo compartilhado. É o mecanismo mais comum de assinatura de webhooks.
HTTP: Protocolo de comunicação da web. Toda chamada de API REST é uma requisição HTTP com método, cabeçalhos, corpo e código de resposta.
HTTPS: HTTP sobre conexão criptografada com TLS. Obrigatório em qualquer tráfego que envolva credenciais ou dados de pagamento.
Idempotência: Propriedade que garante que repetir a mesma operação produz o mesmo resultado. Em pagamentos, impede cobrança duplicada em retentativa. Idempotência na API
JSON: Formato de troca de dados em texto, usado no corpo das requisições e respostas da API.
JWT: Formato de token assinado que carrega informações no próprio conteúdo, muito usado em sessões de usuário.
Latência: Tempo entre a requisição e a resposta. Em checkout, latência alta na criação da cobrança derruba conversão.
Ledger: Registro financeiro imutável, atualizado por evento, usado como fonte única da verdade sobre valores e taxas.
OAuth: Protocolo de autorização que permite a um sistema agir em nome de um usuário sem receber a senha dele.
OpenAPI: Especificação padronizada que descreve uma API HTTP de forma legível por máquina, usada para gerar clientes e importar coleções. OpenAPI da Pitra
Paginação: Técnica de dividir uma lista longa em páginas menores, entregues sob demanda.
Payload: Conteúdo transportado numa requisição ou evento — o corpo do JSON enviado ou recebido.
Pix: Sistema brasileiro de pagamentos instantâneos, disponível 24 horas por dia, operado sob regras do Banco Central.
Polling: Consultar periodicamente o status de um recurso. Funciona como reforço, mas é mais lento e mais caro do que receber webhook.
Produção: Ambiente real, com credenciais reais e dinheiro real. A troca de ambiente é feita apenas pela credencial usada.
QR Code: Representação visual de um payload. No Pix, carrega os dados necessários para o aplicativo do banco montar a transferência. QR Code Pix
QR Code dinâmico: QR Code gerado para uma cobrança específica, com valor, identificador e prazo próprios — o que permite conciliação automática.
Rate limit: Limite de requisições por período. Ao ser atingido, a API responde 429 e o cliente deve aplicar backoff. Rate limits
Reenvio de webhook: Política de repetição do envio de um evento quando a aplicação não responde com sucesso, normalmente com intervalos crescentes.
REST: Conjunto de convenções sobre HTTP: recursos identificados por URL, verbos com significado fixo e códigos de status padronizados. REST API Pix
Sandbox: Ambiente de testes isolado, onde é possível executar o fluxo completo sem movimentar dinheiro real. Ambientes
SDK: Biblioteca que encapsula as chamadas HTTP da API, oferecendo tipos, retentativa e validação de assinatura prontos. SDK oficial
Swagger: Nome antigo do padrão que deu origem ao OpenAPI, ainda usado para se referir às ferramentas que consomem a especificação.
Timeout: Tempo máximo de espera por uma resposta. Definir timeout é o que impede uma chamada lenta de travar a aplicação inteira.
TLS: Protocolo de criptografia que protege os dados em trânsito entre cliente e servidor, impedindo leitura e adulteração no caminho.
Token: Credencial usada para autenticar chamadas. Na API da Pitra, a API Key é enviada como Bearer token no cabeçalho Authorization.
Webhook: Requisição HTTP enviada pelo provedor para a sua aplicação quando um evento acontece, como a aprovação de um pagamento. Webhook Pix