Integrar Pix por API significa lidar com siglas do arranjo Pix e com conceitos de API que nem sempre vêm explicados. Este glossário reúne os dois lados. Os termos do Pix, como txid, End-to-end ID, BR Code, PSP e DICT, seguem a documentação oficial do Banco Central. Os termos de integração, como webhook e idempotência, mostram como funcionam na prática na API Pix da xFlow.
Cada verbete cabe em poucos minutos de leitura e aponta para os termos relacionados. Se você está começando a integração, a área de desenvolvedores e a tabela de erros da API Pix completam o caminho.
GlossárioO que é API RESTAPI REST é uma interface que expõe recursos em endereços HTTP e usa os métodos do próprio protocolo, como GET e POST, para consultar e alterar esses recursos. Cada requisição leva tudo o que o servidor precisa para responder, e o resultado volta com um código de status HTTP.GlossárioO que é BR CodeBR Code é o padrão de QR Code para iniciar pagamentos adotado no Brasil, baseado no padrão EMV e documentado pelo Banco Central. O Pix copia e cola é o mesmo conteúdo do QR Code em forma de texto, e na API da xFlow ele vem no campo pix.copyPaste.GlossárioO que é cash-in e cash-outCash-in é a entrada de dinheiro numa conta e cash-out é a saída. Numa API Pix, o cash-in é a cobrança paga pelo cliente e o cash-out, também chamado de Pix out, é o envio do saldo para uma chave Pix ou um QR Code.GlossárioO que é chave aleatória (EVP)Chave aleatória é a chave Pix gerada pelo próprio DICT no formato UUID, chamada de EVP (Endereço Virtual de Pagamento) na especificação da API do DICT. Ela não carrega CPF, telefone nem e-mail, e na API da xFlow corresponde ao tipo EVP do campo pix_key_type.GlossárioO que é chave de APIChave de API é a credencial que identifica o sistema que está chamando uma API e autoriza as chamadas que ele faz. Quem tem a chave age em nome da conta, por isso o segredo fica só no servidor e é trocado ao primeiro sinal de vazamento.GlossárioO que é DICTDICT é o Diretório de Identificadores de Contas Transacionais, o serviço do Pix que guarda as chaves Pix e devolve os dados da conta de quem vai receber. É ele que permite pagar com CPF, CNPJ, telefone, e-mail ou chave aleatória, sem digitar agência e conta.GlossárioO que é End-to-end IDEnd-to-end ID (EndToEndId) é o identificador único de uma transação Pix na liquidação. Na API da xFlow, ele aparece no campo pix.endToEnd das cobranças pagas e serve, junto com os dados do pagador, para conciliar o recebimento com o extrato.GlossárioO que é HMACHMAC é um código de autenticação de mensagem calculado com uma função de hash e uma chave secreta que só as duas pontas conhecem. Com HMAC-SHA256, quem recebe a mensagem confirma que ela veio de quem tem o segredo e que nenhum byte mudou no caminho.GlossárioO que é idempotênciaIdempotência é a propriedade de uma operação que produz o mesmo efeito quando executada uma ou várias vezes. Em uma API de pagamento, é o que garante que repetir uma chamada depois de uma falha de rede não crie uma segunda cobrança nem um segundo saque.GlossárioO que é ISPBISPB é o Código Identificador no Sistema de Pagamentos Brasileiro, o código de 8 caracteres que identifica cada instituição nos sistemas de pagamento do Banco Central. No Pix, é por ele que se sabe em qual participante o recebedor tem a conta.GlossárioO que é payloadPayload é o conteúdo útil de uma mensagem: os dados que interessam, sem os cabeçalhos e o envelope que os transportam. Numa API, é o corpo JSON da requisição ou da resposta, e no Pix é também o texto do QR Code no padrão BR Code e o JSON para o qual o QR Code dinâmico aponta.GlossárioO que é PSPPSP é a sigla de Prestador de Serviços de Pagamento: no Pix, a instituição participante em que o pagador ou o recebedor tem a conta transacional. Em todo Pix há o PSP do pagador e o PSP do recebedor, que podem ser a mesma instituição.GlossárioO que é rate limitRate limit é o limite de requisições que uma API aceita de um mesmo cliente em um intervalo de tempo. Acima dele, a API responde 429 Too Many Requests, e o cliente deve esperar antes de tentar de novo.GlossárioO que é SPISPI é o Sistema de Pagamentos Instantâneos, a infraestrutura centralizada do Banco Central que liquida os Pix entre instituições diferentes. Cada transação é liquidada individualmente nas Contas PI dos participantes diretos, e a liquidação não pode ser desfeita.GlossárioO que é txidtxid (transactionId) é o identificador da transação na perspectiva de quem recebe: o código que o recebedor atribui a uma cobrança Pix para conciliar o pagamento. Ele viaja com o Pix até o PSP do recebedor, que o usa para avisar que aquela cobrança foi liquidada.GlossárioO que é webhookWebhook é uma requisição HTTP que um sistema envia para a sua URL quando um evento acontece, sem que você precise perguntar. Em pagamentos Pix, é o jeito de saber que uma cobrança foi paga, um estorno concluiu ou um saque falhou.GlossárioO que são códigos de status HTTPCódigos de status HTTP são os números de três dígitos que um servidor devolve para dizer o resultado de uma requisição. O primeiro dígito indica a família: 2xx deu certo, 4xx o problema está no pedido e 5xx a falha foi do lado do servidor ou de um sistema que ele chamou.