Vender com PIX ou boleto

Separe o código da oferta

A cobrança precisa de uma oferta. Envie o código da oferta no campo offer_identifier. É o identifier que voltou quando você criou a oferta.

Na hora da cobrança, a API confere a oferta:

Também dá para informar a oferta na hora, com o campo offer no lugar de offer_identifier. Nunca envie os dois. Veja Ofertas, planos e ofertas ocultas.

Crie a cobrança

Envie uma Idempotency-Key única para esta cobrança e grave no seu pedido antes de enviar. Veja Idempotência.

O exemplo cria um PIX:

curl -X POST "https://api.pagpolar.com/v1/payments/pix" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
  -H "Idempotency-Key: 3c8e1f7a-2b4d-4e6f-9a1c-5d7e9f0a1b2c" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_identifier": "<CODIGO_DA_OFERTA>",
    "external_reference": "PEDIDO-0002",
    "customer": {
      "name": "Maria Silva",
      "email": "cliente@exemplo.com",
      "document": "<CPF_DO_CLIENTE>",
      "phone": "<TELEFONE_DO_CLIENTE>"
    }
  }'

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID();

const response = await fetch('https://api.pagpolar.com/v1/payments/pix', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    offer_identifier: '<CODIGO_DA_OFERTA>',
    external_reference: 'PEDIDO-0002',
    customer: {
      name: 'Maria Silva',
      email: 'cliente@exemplo.com',
      document: '<CPF_DO_CLIENTE>',
      phone: '<TELEFONE_DO_CLIENTE>',
    },
  }),
});

console.log(response.status, await response.json());

Para o boleto, o corpo é o mesmo. Só a rota muda: POST /payments/boleto.

Campos do corpo:

Dados do cliente:

Campos opcionais:

Não envie installments. No PIX e no boleto, o único valor aceito é 1.

Resposta 201 do PIX:

{
  "data": {
    "offer_identifier": "PPP1234567890",
    "transactions": ["a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"],
    "pix": {
      "qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d"
    }
  }
}

Resposta 201 do boleto:

{
  "data": {
    "offer_identifier": "PPP1234567890",
    "transactions": ["b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"],
    "boleto": {
      "barcode": "34191.79001 01043.510047 91020.150008 1 96610000015000",
      "pdf_link": "https://boletos.pagpolar.com/a1b2c3d4.pdf"
    }
  }
}

As duas respostas estão resumidas. Contrato completo: POST /payments/pix e POST /payments/boleto.

Guarde transactions[0] junto do seu pedido. Ele é o id da venda. Você vai usar esse valor para ligar o webhook ao pedido e para consultar a venda.

Mostre o PIX ou o boleto ao cliente

PIX. Mostre pix.qr_code como código "copia e cola". Se quiser mostrar a imagem do QR Code, gere a imagem a partir desse texto.

• O PIX é criado com validade de 5 horas.
• A data e a hora exatas do vencimento aparecem em payment_details.qr_code_expires_at quando você consulta a venda (passo 5).

Boleto. Mostre o link boleto.pdf_link para o cliente abrir e pagar.

• O boleto é criado com vencimento em 5 dias.
• boleto.barcode traz o código do boleto como o gateway devolveu.

Espere o webhook

A PagPolar envia um POST para a URL do webhook da sua credencial a cada mudança importante. Autentique a requisição e descarte repetidos: veja Autenticar requisições e Processar sem duplicar.

Exemplo de TRANSACTION_PAID de um PIX (resumido):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "TRANSACTION_PAID",
  "creation_date": "2026-09-15T14:35:10.000Z",
  "version": "1.0.0",
  "data": {
    "transaction": {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "identifier": "PPO9876543210",
      "status": "PAID",
      "payment_method": "PIX",
      "total_amount": "10.0000",
      "net_amount": 10,
      "paid_at": "2026-09-15T14:35:00.000Z"
    },
    "source": {
      "channel": "API",
      "api_credential_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  }
}

Use data.transaction.id, o mesmo valor de transactions[0], para achar o seu pedido: o webhook não traz a external_reference. Decida pelo data.transaction.status, que é o estado da venda no momento do envio. Veja todos os campos em Formato do evento.

Consulte a venda

Use a consulta quando precisar do status atual: o webhook atrasou, o seu servidor ficou fora do ar ou você quer conferir antes de liberar.

Envie o id que veio em transactions[0]:

curl "https://api.pagpolar.com/v1/sales/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"

const response = await fetch(
  'https://api.pagpolar.com/v1/sales/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d',
  { headers: { Authorization: `Bearer ${accessToken}` } },
);

console.log(response.status, await response.json());

Resposta 200 (resumida):

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "identifier": "PPO9876543210",
    "external_reference": "PEDIDO-0002",
    "status": "PAID",
    "payment_method": "PIX",
    "total_amount": 10,
    "paid_at": "2026-09-15T14:35:00.000Z",
    "payment_details": {
      "qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d",
      "qr_code_expires_at": "2026-09-15T19:30:00.000Z",
      "billet_barcode": null,
      "billet_link": null,
      "last_credit_card_digits": null
    }
  }
}

total_amount vem em reais: 10 na API e "10.0000", como texto, no webhook. Veja Valores nas respostas.

Você também pode consultar pelo código da venda (GET /sales/PPO9876543210) ou pela sua referência (GET /sales/PEDIDO-0002). GET /payments/{identifier} faz a mesma consulta. Veja Como a venda é encontrada.

Contrato completo: GET /sales/{identifier}.