Como funciona a API Pix da PixGo

A API de pagamento Pix da PixGo é REST e troca dados em JSON. As chamadas partem da URL base https://pixgo.org/api/v1 e são autenticadas pelo header X-API-Key, com a sua PixGo Key (formato pk_ seguido de uma sequência aleatória).

  1. Seu backend chama POST /api/v1/payment/create com o valor e o CPF ou CNPJ de quem vai pagar.
  2. A resposta traz o payment_id, o qr_code (o Pix Copia e Cola) e o qr_image_url, com a imagem do QR Code para exibir ao cliente.
  3. Com o Pix confirmado, a PixGo envia o evento payment.completed ao seu webhook e você libera o pedido.

Não há SDK oficial: qualquer linguagem que faça requisições HTTP integra. A documentação da API traz exemplos em PHP e Node.js, e o guia para desenvolvedores inclui Python.

Quer integrar o Pix no seu sistema?

Ver a documentação

Endpoints da API de pagamento Pix

Método e rotaPara que serve
POST /api/v1/payment/createCria a cobrança e devolve o QR Code, com HTTP 201.
GET /api/v1/payment/{id}/statusStatus atual, com o CPF do pagador mascarado. Limite de 1.000 requisições por 24 horas.
GET /api/v1/payment/{id}Detalhes completos do pagamento.
GET /api/v1/paymentsBusca pelo seu external_id. Sempre devolve uma lista.

Os status documentados são pending, completed, expired e cancelled; estornos aparecem como refunded. Em estado final, a rota de detalhes responde HTTP 410 com "terminal": true e o mesmo corpo do 200: não é erro, o pagamento só não muda mais. Para o prazo de pagamento, use sempre o campo expires_at em vez de assumir um tempo fixo.

Campos obrigatórios e exemplo de requisição

Dois campos são obrigatórios na criação:

  • amount: valor em reais, com mínimo de R$ 10,00 e máximo conforme o nível da sua conta.
  • receiver_cpf: CPF (11 dígitos) ou CNPJ (14 dígitos) de quem vai pagar, só números e com dígito verificador válido. Sem ele, a API responde 422 PAYER_DOC_REQUIRED.

O receiver_cpf é uma trava de titularidade: só esse documento consegue pagar o QR Code. Se outra pessoa pagar, o pagamento é rejeitado automaticamente e o estorno pode levar até 48 horas.

São opcionais receiver_name, receiver_email, receiver_phone, receiver_address, description, external_id (até 50 caracteres) e webhook_url.

curl -X POST https://pixgo.org/api/v1/payment/create \
  -H "X-API-Key: SUA_PIXGO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00, "receiver_cpf": "12345678901", "external_id": "pedido_123", "webhook_url": "https://seusite.com/webhook/pixgo"}'

Guarde o payment_id junto do seu external_id. Os erros chegam com success: false e um código estável no campo error, como INVALID_API_KEY, LIMIT_EXCEEDED e RATE_LIMIT_EXCEEDED: trate pelo código, não pelo texto. Veja os códigos de erro da API.

Webhooks assinados com HMAC-SHA256

As notificações vão para o webhook_url de cada cobrança ou para os webhooks cadastrados no painel, em Minha Loja, que valem para a conta inteira. Os eventos são order.created, payment.completed, payment.expired e payment.refunded.

Seu endpoint precisa aceitar POST em HTTPS, num domínio público, e responder 2xx para confirmar o recebimento. localhost, 127.0.0.1 e IPs privados são recusados.

Cada entrega traz os headers X-Webhook-Event, X-Webhook-Timestamp e X-Webhook-Signature. Para validar:

  1. Concatene o X-Webhook-Timestamp, um ponto e o corpo bruto da requisição.
  2. Calcule o HMAC-SHA256 dessa string com o seu Webhook Secret, exibido na página API Keys, junto da PixGo Key.
  3. Compare com X-Webhook-Signature de forma timing-safe. Se não bater, rejeite.

O payload de payment.completed traz os objetos customer, payer (com CPF mascarado), product e amounts, em que net é o valor líquido que você recebe. Use payment_id mais event como chave única para ignorar entregas repetidas e, em pagamentos críticos, confirme o status na consulta antes de liberar o produto.

Como obter a PixGo Key

A chave é liberada depois de uma verificação de compliance contra fraude:

  1. Crie sua conta e valide o endereço da sua carteira Liquid: a API exige carteira validada.
  2. No painel, abra o menu API Keys e clique em Solicitar acesso.
  3. A PixGo valida a conta e a resposta chega por e-mail.

Aprovado o acesso, a PixGo Key aparece na mesma página. É uma chave por usuário: guarde-a em variável de ambiente no servidor, nunca em código que roda no navegador ou em repositório público.

Taxas, limites e recebimento em DePix no D+1

A API e os webhooks não são cobrados. Você paga só as taxas das vendas recebidas, as mesmas de qualquer cobrança na PixGo:

  • 2% do valor nas cobranças a partir de R$ 50,00;
  • 2% + R$ 1,00 nas cobranças de R$ 10,00 a R$ 49,99;
  • R$ 0,50 fixos pelo envio D+1 para a sua carteira.

O teto por QR Code acompanha o nível da conta, que sobe automaticamente com os pagamentos confirmados. Não há limite de cobranças por dia. Cada chave tem limite padrão de 10.000 requisições por 24 horas. Detalhes em limites por QR Code e por pagador.

O valor confirmado chega em DePix na sua carteira Liquid no D+1, em dia corrido: pagou hoje, o DePix cai até as 23h59 de amanhã, inclusive em fins de semana e feriados, com o endereço da carteira validado no perfil. Veja como funciona o D+1.

Casos de uso: checkout, recorrência e automação

  • Loja própria ou SaaS: crie a cobrança no fechamento do pedido e libere o produto no payment.completed. Sem programar, use o checkout Pix pronto.
  • Assinaturas: não há endpoint nativo de assinatura nem Pix Automático na PixGo; sua rotina cria uma cobrança a cada vencimento. Veja o guia de recorrência com a API ou o módulo de cobrança recorrente Pix.
  • WhatsApp: um bot gera a cobrança pela API e envia o QR Code na conversa, como no tutorial ChatGPT + API PixGo.
  • WooCommerce, Shopify e similares: não há plugin oficial; a integração é um módulo próprio que chama a API REST. Para a visão geral, veja o gateway Pix da PixGo.

Como começar

  1. Crie a conta e valide a carteira: Cadastre-se na PixGo e valide o endereço da sua carteira Liquid. Sem isso, a API não é liberada.
  2. Solicite acesso em API Keys: Descreva o seu negócio e aguarde a validação da conta para receber a chave.
  3. Guarde as credenciais no servidor: Coloque a PixGo Key e o Webhook Secret em variáveis de ambiente. Eles nunca vão para o front-end.
  4. Crie a primeira cobrança: Envie um POST para /api/v1/payment/create com amount, receiver_cpf e external_id, e mostre o qr_code ao cliente.
  5. Valide o webhook: Confira a assinatura HMAC-SHA256 e trate payment.completed, payment.expired e payment.refunded.
  6. Teste com valor baixo: Toda chave é de produção. Faça os primeiros testes com cobranças de R$ 10,00.

Perguntas frequentes

A API Pix da PixGo tem sandbox?

Não. Toda chave é de produção e não existe ambiente de teste separado; teste com cobranças a partir de R$ 10,00.

O campo receiver_cpf é obrigatório?

Sim. Sem o CPF ou CNPJ do pagador a API responde 422 PAYER_DOC_REQUIRED, e só esse documento consegue pagar o QR Code.

Posso chamar a API direto do navegador ou do app?

Não. A PixGo Key não pode ficar em código client-side; faça as chamadas pelo seu backend.

Como confirmo que o webhook veio da PixGo?

Calcule o HMAC-SHA256 do timestamp, um ponto e o corpo bruto com o seu Webhook Secret, e compare com o header X-Webhook-Signature.

Perdi o payment_id. Como encontro a cobrança?

Use GET /api/v1/payments com o parâmetro external_id. Sem resultados, a resposta é HTTP 200 com a lista vazia.

Por que a consulta de detalhes respondeu HTTP 410?

O pagamento chegou a um estado final, como expirado ou estornado. O corpo é igual ao do 200 e deve ser tratado como resposta válida.

Existe SDK oficial da API Pix?

Não. A API é REST com JSON e funciona com qualquer linguagem que faça requisições HTTP.

Quando recebo o valor das cobranças pagas?

Em DePix, na sua carteira Liquid, no D+1 em dia corrido. O campo amounts.net do webhook mostra o líquido.

Outras soluções da PixGo