Início rápido

Este guia mostra o fluxo completo de integração: autenticar, criar uma cobrança Pix, exibir para o pagador e confirmar o recebimento.

Pré-requisitos

• Um token de acesso fornecido pela Paggpix (ver Autenticação).
• A base URL de produção:

https://public-api.paggpix.com

1. Criar uma cobrança

Envie o valor e o CNPJ ou CPF de destino para gerar a cobrança. Informe exatamente um identificador de destino e use o valor como string decimal, com mínimo de 0.03.

curl -X POST https://public-api.paggpix.com/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <suas_credenciais_em_base64>" \
  -d '{
    "cnpj": "75.358.868/0001-67",
    "value": "9.99",
    "description": "Pagamento pedido #999"
  }'

const axios = require('axios');

const CLIENT_ID = '<seu_client_id>';
const CLIENT_SECRET = '<seu_client_secret>';
const CREDENTIALS = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');
const BASE_URL = 'https://public-api.paggpix.com';

const { data } = await axios.post(
  `${BASE_URL}/payments`,
  { cnpj: '75.358.868/0001-67', value: '9.99', description: 'Pagamento pedido #999' },
  { headers: { Authorization: `Basic ${CREDENTIALS}` } },
);

console.log(data.pix_id, data.pix_code);

Veja todos os parâmetros e campos em Criar pagamento.

2. Exibir o Pix para o pagador

A resposta traz duas formas de pagamento, use a que fizer sentido para sua interface:

• pix_code — código Pix copia e cola (BR Code). Exiba como texto com um botão "copiar".
• qrcode_image — imagem do QR Code em base64. Renderize direto em uma tag de imagem:

<img src="data:image/png;base64,QRCODE_IMAGE_AQUI" alt="QR Code Pix" />

3. Confirmar o pagamento

Há duas formas de saber quando a cobrança foi paga:

Webhooks (recomendado)

Cadastre um webhook uma vez e receba uma notificação automática a cada mudança de status, sem ficar consultando a API. Veja Criar webhook e Eventos de webhook.

Verificação sob demanda

Se preferir consultar pontualmente, use o endpoint de verificação com o pix_id retornado:

curl https://public-api.paggpix.com/payments/{pix_id}/verify \
  -H "Authorization: Basic <suas_credenciais_em_base64>"

O campo status retorna o estado atual da cobrança. Entenda cada valor em Ciclo de vida do pagamento.

Próximos passos

• Autenticação — como obter e enviar seu token
• Ciclo de vida do pagamento — estados e transições
• Eventos de webhook — verificação de assinatura e payloads
• Erros — formato de erro e códigos de status