Perguntas frequentes sobre Pix, API e pagamentos

111 respostas objetivas sobre integração, webhooks, cobranças, segurança e a plataforma da Pitra.

API Pix

O que é uma API Pix?
É a interface programável que permite a um sistema criar cobranças Pix, receber a confirmação do pagamento e conciliar os valores automaticamente, sem passo manual no aplicativo do banco.
Como funciona uma cobrança Pix por API?
A aplicação autentica-se, cria a cobrança informando valor e dados do cliente, recebe o QR Code e o Copia e Cola, e é avisada por webhook assim que o pagamento é liquidado.
Preciso saber programar para usar uma API Pix?
Para usar a API, sim. Quem não programa pode usar o checkout pronto por link, que não exige código.
Quanto tempo leva para integrar uma API Pix?
Uma integração básica de cobrança e webhook costuma levar poucas horas com documentação e SDK. O tempo maior fica no tratamento de erros e na conciliação.
A API Pix funciona em finais de semana e feriados?
Sim. O Pix opera 24 horas por dia, todos os dias do ano.
Qual é a diferença entre API Pix e chave Pix?
A chave Pix identifica a conta que recebe. A API é o meio programático de criar cobranças e receber confirmações vinculadas a essa conta.
Posso usar a API Pix em aplicativo mobile?
Sim, desde que a cobrança seja criada no seu servidor. A credencial secreta nunca deve ficar dentro do aplicativo.
A API Pix da Pitra é REST?
Sim, é uma API REST com autenticação por Bearer token e respostas em JSON.
Existe limite de cobranças por dia?
Existe limite de requisições por período, aplicado para proteger a plataforma. Ele é documentado na página de rate limits.
Como testo a API antes de vender de verdade?
Use a credencial de teste. O fluxo completo funciona sem movimentar dinheiro real.

Webhook

O que é um webhook?
É uma requisição HTTP enviada pelo provedor para a sua aplicação quando um evento acontece, como um pagamento aprovado.
Preciso mesmo de webhook?
Na prática, sim. Sem ele, a única alternativa é consultar o status repetidamente, o que é mais lento e mais caro.
Como valido a assinatura de um webhook?
Recalcule o HMAC sobre o corpo bruto da requisição usando o segredo compartilhado e compare com o cabeçalho de assinatura, em comparação de tempo constante.
Por que a assinatura nunca bate?
Quase sempre porque a validação foi feita sobre o JSON já convertido, e não sobre o corpo bruto recebido.
Meu endpoint pode ser HTTP?
Não. O endpoint precisa ser HTTPS, já que o payload contém dados de pagamento.
O que devo responder no webhook?
Um código 2xx o mais rápido possível. Grave o evento e processe o restante em segundo plano.
O que acontece se meu servidor estiver fora do ar?
O provedor reenvia o evento com intervalos crescentes. Ao voltar, sua aplicação recebe o que perdeu.
Posso receber o mesmo evento duas vezes?
Sim. Reenvio é parte do desenho de entrega, então o consumo precisa ser idempotente.
Os eventos chegam em ordem?
Não há garantia de ordem. Verifique o status atual antes de regredir o estado de um pedido.
Como testo um webhook em ambiente local?
Use um túnel HTTPS para expor sua máquina, ou implante o endpoint em um ambiente de testes acessível pela internet.
Preciso guardar o histórico de webhooks?
Recomenda-se guardar o identificador dos eventos processados, tanto para idempotência quanto para auditoria.
Qual timeout devo esperar do provedor?
Provedores geralmente aguardam poucos segundos. Por isso a resposta deve ser imediata e o processamento assíncrono.

Gateway

O que é um gateway Pix?
É a camada de software entre a sua aplicação e a infraestrutura financeira, responsável por cobranças, webhooks, histórico e conciliação.
Qual a diferença entre gateway e adquirente?
O gateway é a camada de software e integração; a adquirente é a instituição que processa e liquida o pagamento.
Vale a pena integrar direto com o banco?
Faz sentido em operações grandes, com time dedicado. Para a maioria, o custo de contrato, homologação e manutenção não compensa.
Posso trocar de gateway depois?
Sim. Escolher um que exponha os dados por API e permita exportação reduz muito o custo dessa troca.
O gateway fica com meu dinheiro?
Depende do modelo de cada provedor. Verifique sempre qual instituição é responsável pela conta de recebimento.
Gateway Pix precisa de autorização do Banco Central?
A prestação de serviços de pagamento é regulada. O papel exato depende do modelo de operação de cada empresa.
Como avalio a confiabilidade de um gateway?
Página de status pública, changelog, documentação atualizada, webhooks assinados, idempotência documentada e suporte acessível.
Vale construir meu próprio gateway?
Só quando o pagamento é o produto. Caso contrário, o esforço de idempotência, fila de eventos e conciliação não se paga.

SDK

O que é um SDK de pagamentos?
Uma biblioteca que encapsula as chamadas HTTP da API, entregando tipos, retentativa e validação de assinatura prontos.
Preciso usar o SDK?
Não. A API é REST e pode ser chamada por qualquer cliente HTTP. O SDK apenas reduz erros comuns.
O SDK da Pitra é para qual linguagem?
O SDK oficial é para Node.js e TypeScript. Outras linguagens podem usar a API diretamente ou gerar cliente pelo OpenAPI.
O SDK cuida de idempotência?
Sim, as operações de criação enviam chave de idempotência automaticamente.
O SDK valida webhook?
Sim, existe um método para validar a assinatura a partir do corpo bruto e do segredo.
O SDK faz retentativa sozinho?
Ele aplica retentativa com backoff em falhas temporárias, como erros de rede e respostas 5xx.
Como atualizo o SDK com segurança?
Acompanhe o changelog, atualize primeiro em ambiente de teste e rode seus testes automatizados antes de subir.
Posso usar o SDK no front-end?
Não. Ele usa a chave secreta, que só pode existir no servidor.

OpenAPI

O que é OpenAPI?
Um formato padronizado para descrever uma API HTTP: endpoints, parâmetros, respostas, autenticação e erros.
Para que serve a especificação na prática?
Para importar a coleção no Postman, gerar clientes, validar contratos em teste e alimentar ferramentas de IA com o contrato correto.
JSON ou YAML: qual devo usar?
São o mesmo conteúdo. Ferramentas costumam preferir JSON; humanos costumam preferir YAML.
A especificação fica desatualizada?
Só quando não é gerada a partir da mesma fonte da API. Na Pitra, a especificação, a documentação e o SDK compartilham a mesma origem.
Como importo no Postman?
Baixe o arquivo da especificação e use a opção de importar do Postman: a coleção completa é criada automaticamente.
Posso gerar um cliente em Python ou PHP?
Sim, com qualquer gerador compatível com OpenAPI, usando a especificação publicada.
OpenAPI substitui a documentação?
Não. Ela descreve o contrato; guias, conceitos e exemplos continuam necessários.

Pix

O que é Pix?
É o sistema brasileiro de pagamentos instantâneos, disponível 24 horas por dia, operado sob regras do Banco Central.
Qual a diferença entre QR Code estático e dinâmico?
O estático é reutilizável e não expira; o dinâmico tem valor, identificador e prazo próprios, o que permite conciliação automática.
O que é o Pix Copia e Cola?
É o mesmo conteúdo do QR Code em formato de texto, no padrão EMV.
Pix tem chargeback?
Não no modelo de cartão. Existem mecanismos específicos para casos de fraude, mas a devolução comum depende de acordo entre as partes.
Pix pode ser estornado?
Sim, é possível devolver total ou parcialmente o valor recebido ao pagador.
Quanto tempo leva para o Pix cair?
Segundos, na maior parte das transações.
Pix funciona para produto digital?
Funciona muito bem: como a confirmação é imediata, a entrega pode ser automática.
O cliente precisa ter conta na minha plataforma para pagar?
Não. O pagamento é feito no aplicativo do banco do próprio cliente.
O QR Code Pix expira?
O dinâmico sim, conforme o prazo definido na cobrança.
Posso receber Pix de qualquer banco?
Sim. O Pix é interoperável entre as instituições participantes.

Cobranças

Quais são os status de uma cobrança?
Tipicamente pendente, aprovada, expirada, cancelada e estornada.
Posso alterar o valor de uma cobrança criada?
Não. Cancele e crie uma nova cobrança com o valor correto.
O que fazer quando a cobrança expira?
Ofereça ao cliente a geração de uma nova cobrança, mantendo o mesmo pedido.
Devo criar uma cobrança nova a cada visita à tela?
Não. Reaproveite a cobrança válida existente para não poluir o histórico e a conciliação.
Como amarro o pagamento ao pedido?
Guarde o identificador da cobrança junto ao pedido no momento da criação.
Como consulto uma cobrança?
Pelo endpoint de consulta, usando o identificador retornado na criação.
O que é uma cobrança duplicada?
Duas cobranças criadas para o mesmo pedido, normalmente por retentativa sem chave de idempotência.
Como listo minhas vendas por período?
Pelo endpoint de vendas, com paginação por cursor e filtros documentados.
Consigo exportar as vendas?
Sim, o painel oferece exportação e a API permite ler as vendas de forma paginada.

Checkout

O que é um checkout Pix?
É a tela onde o cliente confirma a compra e paga com Pix.
Quando usar checkout pronto em vez de API?
Quando o objetivo é vender rápido por link, redes sociais ou WhatsApp, sem construir tela própria.
O checkout funciona no celular?
Sim, e no celular o Copia e Cola é o caminho principal, já que não há segunda câmera para ler o QR Code.
A tela atualiza sozinha quando o cliente paga?
Sim, o checkout acompanha o status e mostra a confirmação sem o cliente precisar recarregar.
Posso personalizar o checkout?
O checkout da Pitra permite configurar informações do produto e da loja. Personalização total exige construir a própria tela via API.
Quantos campos devo pedir no checkout?
Apenas os necessários para identificar a compra e entregar o produto. Cada campo extra reduz conversão.
O checkout envia o acesso automaticamente?
Sim, quando o produto tem entrega configurada, a liberação acontece após a confirmação do pagamento.
Como recupero uma venda não finalizada?
A plataforma registra o checkout iniciado e permite retomar o pagamento pelo mesmo link enquanto a cobrança estiver válida.

Segurança

Onde devo guardar minha API Key?
Em variável de ambiente no servidor. Nunca no front-end, nunca em repositório público.
O que faço se minha chave vazar?
Revogue a chave imediatamente pelo painel e gere uma nova.
Como impeço um pagamento falso?
Validando a assinatura de todo webhook recebido e nunca liberando entrega a partir de informação vinda do navegador.
Preciso de HTTPS?
Sim, em todas as chamadas e no endpoint de webhook.
O que não deve aparecer nos logs?
Chaves, tokens, cabeçalho de autorização e dados pessoais do pagador.
A Pitra expõe dados de clientes de outras lojas?
Não. Cada consulta é escopada à loja autenticada; o isolamento é verificado por testes automatizados.
Como funciona o controle de acesso ao painel?
Por autenticação de usuário, com papéis distintos e verificação no servidor a cada operação sensível.
Os dados são tratados conforme a LGPD?
Sim. A plataforma coleta o mínimo necessário para processar o pagamento e entregar o produto, e restringe o acesso a esses dados.
Posso usar a API Key no navegador?
Não. Qualquer chave enviada ao navegador deve ser considerada pública.

Integração

Por onde começo a integração?
Pelo quickstart: criar conta, gerar chave de teste, criar a primeira cobrança e configurar o webhook.
Existe template pronto para minha stack?
Há templates oficiais para várias stacks de Node.js, PHP e Python. A lista fica na página de templates.
Posso testar sem escrever código?
Sim, pelo playground, que gera exemplos executáveis em várias linguagens.
Como passo de teste para produção?
Trocando a credencial pela de produção, depois de validar o fluxo completo em teste.
O que é idempotência e por que preciso dela?
É a garantia de que repetir a mesma operação não cria duas cobranças. É requisito em qualquer operação que mova dinheiro.
Como trato o erro 429?
Aplicando espera crescente entre as tentativas, respeitando os limites documentados.
Como trato erros 5xx?
São falhas temporárias do lado do provedor: podem ser repetidas com backoff e a mesma chave de idempotência.
Como trato erros 400?
São erros de payload. Corrija os campos antes de repetir; repetir sem corrigir só gera o mesmo erro.
Preciso de fila para processar webhooks?
Não é obrigatório, mas ajuda: responder rápido e processar depois reduz reenvios desnecessários.
Como monitoro a saúde da integração?
Acompanhando latência de criação de cobrança, taxa de erro por endpoint, entregas de webhook com falha e cobranças pendentes antigas.
Posso usar IA para escrever a integração?
Sim. A Pitra publica manifestos de IA e uma especificação OpenAPI justamente para que assistentes gerem código correto.

Documentação

Onde fica a documentação da API?
Na área de documentação da Pitra, organizada por objetivo: começar, referência, webhooks, SDK e OpenAPI.
Existe changelog?
Sim, com as mudanças relevantes de API, SDK e plataforma.
Existe página de status?
Sim, com a disponibilidade dos serviços.
A documentação tem exemplos executáveis?
Sim, gerados a partir da mesma fonte que alimenta o SDK e a especificação OpenAPI.
Onde vejo o catálogo de erros?
Na página de erros da documentação, com código, causa provável e ação recomendada.
Onde encontro os eventos de webhook?
Na página de eventos, com o payload de cada tipo de notificação.
Como sei qual versão da API estou usando?
A versão fica indicada na documentação e na especificação OpenAPI.

Pitra

O que é a Pitra?
É uma infraestrutura brasileira de pagamentos Pix: API REST, checkout pronto, webhooks assinados, SDK e documentação técnica.
Como crio uma conta?
Pelo cadastro gratuito no site. A conta dá acesso ao painel e à geração de chaves de teste.
Preciso pagar mensalidade?
Não há mensalidade. O modelo é por transação, com os valores informados de forma transparente na página inicial.
Quais formas de venda a Pitra oferece?
Checkout por link, para vender sem código, e API Pix, para integrar ao seu próprio sistema.
A Pitra entrega o produto automaticamente?
Sim, produtos digitais podem ser entregues automaticamente após a confirmação do pagamento.
Existe painel para acompanhar as vendas?
Sim, com vendas unificadas de checkout e API, filtros e detalhes de cada transação.
A Pitra tem notificações?
Sim, notificações push para lojistas em eventos como venda aprovada.
Como falo com o suporte?
Pela página de suporte, que reúne perguntas frequentes e o e-mail de atendimento.
A Pitra funciona com WhatsApp?
Sim, há automações de atendimento e entrega por WhatsApp dentro do painel.
Posso emitir relatórios?
Sim, o painel oferece visões consolidadas e exportação de dados da loja.
A Pitra oferece ambiente de testes?
Sim, com credenciais separadas das de produção.
A Pitra tem SDK oficial?
Sim, para Node.js e TypeScript, além da especificação OpenAPI para outras linguagens.

Não achou sua resposta? Veja o glossário, o blog ou fale com o suporte.