Pix QR Code

Gere cobranças Pix dinâmicas pela API. O dinheiro cai direto na conta de recebimento da sua loja.

Cobranças Pix criadas pela API são independentes das vendas de checkout: elas não aparecem em /v1/sales, não disparam entrega automática de produto e possuem eventos próprios.

O objeto cobrança Pix

{
  "object": "pix_payment",
  "id": "3f2a9c11-1c2b-4de5-9a77-0b3f2d1e4c88",
  "status": "pending",
  "amount": 149.9,
  "description": "Mensalidade julho",
  "external_id": "pedido-10231",
  "customer_email": "cliente@exemplo.com",
  "customer": {
    "email": "cliente@exemplo.com",
    "whatsapp": "11999998888",
    "document": "12345678909",
    "name": "Maria Silva"
  },
  "metadata": { "pedido": "10231" },
  "paid_at": null,
  "livemode": true,
  "created_at": "2026-08-01T12:00:00.000Z",
  "pix": {
    "copy_paste": "00020101021226...5802BR",
    "qr_code": "00020101021226...5802BR",
    "qr_code_base64": "iVBORw0KGgoAAAANSUhEUg...",
    "ticket_url": "https://...",
    "expires_at": "2026-08-01T12:30:00.000Z"
  }
}

external_id, paid_at e livemode estão presentes na criação, na consulta, na listagem e em todos os eventos pix.*. Dentro de pix, copy_paste é o código Pix copia e cola; qr_code é mantido como alias do mesmo valor por compatibilidade. livemode é false em cobranças criadas com chaves sk_test_*.

Situações

Status	Significado
`pending`	Cobrança criada, aguardando pagamento.
`paid`	Pagamento confirmado.
`expired`	Prazo de validade encerrado sem pagamento.
`canceled`	Cobrança cancelada ou recusada.
`refunded`	Valor devolvido ao pagador.

Criar cobrança Pix

POST/api/public/v1/payments/pixscope payments:write

curl -X POST https://pitra.com.br/api/public/v1/payments/pix \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-10231" \
  -d '{
    "amount": 149.90,
    "description": "Mensalidade julho",
    "external_id": "pedido-10231",
    "expires_in": 1800,
    "customer": {
      "email": "cliente@exemplo.com",
      "whatsapp": "11999998888",
      "document": "12345678909"
    }
  }'

Campo	Tipo	Descrição
`amount`	number	Obrigatório. Maior que zero, até 999999.99.
`description`	string	Até 200 caracteres. Aparece no extrato do pagador.
`external_id`	string	Seu identificador. Único por loja.
`expires_in`	integer	Validade em segundos: 60 a 86400. Padrão 1800.
`customer`	object	Obrigatório. Dados de contato do pagador.
`customer.email`	string	Obrigatório. E-mail válido do pagador.
`customer.whatsapp`	string	Obrigatório. DDD + número (10 a 13 dígitos).
`customer.document`	string	Opcional (recomendado). CPF do pagador (11 dígitos). Se enviado, precisa ser válido.
`customer.name`	string	Opcional. Nome do pagador.
`metadata`	object	Dados livres devolvidos em consultas e webhooks.

Sem customer.email e customer.whatsapp a cobrança é recusada com 400 invalid_request. O customer.document (CPF) é opcional, mas recomendamos sempre enviar: com o CPF do pagador o provedor reduz bastante os cancelamentos automáticos do QR Code.

Resposta 201 com o objeto cobrança. Reenviar o mesmo external_id devolve 200 com a cobrança já existente, sem duplicar.

Consultar cobrança

GET/api/public/v1/payments/pix/{id}scope payments:read

curl https://pitra.com.br/api/public/v1/payments/pix/3f2a9c11-1c2b-4de5-9a77-0b3f2d1e4c88 \
  -H "Authorization: Bearer sk_live_..."

Cobrança de outra loja devolve 404 not_found.

Consultar por external_id

GET/api/public/v1/payments/pix/external/{external_id}scope payments:read

curl https://pitra.com.br/api/public/v1/payments/pix/external/pedido-10231 \
  -H "Authorization: Bearer sk_live_..."

Consulta pelo identificador que você definiu na criação — útil para ERPs, bots e CRMs que só guardam o próprio número de pedido. Sem cobrança correspondente na sua loja, a resposta é 404 not_found.

Listar cobranças

GET/api/public/v1/payments/pixscope payments:read

curl "https://pitra.com.br/api/public/v1/payments/pix?status=paid&limit=50" \
  -H "Authorization: Bearer sk_live_..."

Parâmetro	Tipo	Descrição
`limit`	integer	1–100, padrão 20.
`starting_after`	string	Cursor da página anterior.
`status`	string	pending, paid, expired, canceled ou refunded.
`external_id`	string	Seu identificador.

Afiliados na sua página de vendas

Quando um afiliado envia tráfego para a sua página de vendas, a Pitra adiciona o parâmetro pit_aff na URL. Leia esse parâmetro no formulário e envie em affiliate_attribution_token ao criar a cobrança: a indicação fica vinculada na hora, antes do pagamento, sem depender de nenhuma inferência por tempo. O token é assinado e validado no servidor — ele nunca define valor, comissão ou produto.

<script>
  // Página de vendas da loja — repassa a indicação do afiliado.
  const pitAff = new URLSearchParams(window.location.search).get("pit_aff");
  if (pitAff) sessionStorage.setItem("pit_aff", pitAff);

  async function criarPix(dadosDoCliente) {
    const token = pitAff || sessionStorage.getItem("pit_aff");
    const resposta = await fetch("/sua-rota-no-backend/pix", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ ...dadosDoCliente, affiliate_attribution_token: token }),
    });
    return resposta.json();
  }
</script>

// No seu backend, repasse o campo para a API da Pitra:
// POST /api/public/v1/payments/pix
// { "amount": 49.9, "customer": { ... }, "affiliate_attribution_token": "<pit_aff da URL>" }

Sem o token, a Pitra ainda tenta atribuir pelo último clique válido do mesmo navegador nos minutos anteriores. Enviar pit_aff é o caminho garantido.

Eventos

Evento	Quando ocorre
`pix.created`	Cobrança criada com sucesso.
`pix.paid`	Pagamento confirmado.
`pix.expired`	Prazo encerrado sem pagamento.

O corpo do evento segue o mesmo envelope dos demais webhooks, com o objeto cobrança em data.object. A verificação de assinatura é idêntica à descrita em Assinatura.

Ambiente de teste

Chaves sk_test_* devolvem um QR Code simulado, sem qualquer movimentação financeira. Use sk_live_* para cobranças reais.

Para gerar cobranças reais a loja precisa estar com a conta de recebimento conectada no painel. Sem isso a criação devolve 400 invalid_request.