Documentação da API PIX

Integre cobranças PIX diretamente no seu site, app ou sistema em minutos.

Simples

Uma chamada POST para gerar o QR Code

Seguro

Autenticação por API Key + HTTPS

Confiável

Webhooks automáticos na confirmação

1. Autenticação

Todas as requisições precisam de uma Chave de API no header. Para gerar a sua, acesse o painel em Integrações → API Pix e clique em Gerar nova chave.

Guarde sua chave em segurança. Ela dá acesso à sua conta e não deve ser exposta no frontend/browser. Use sempre no backend (servidor).

Você pode enviar a chave de duas formas:

http

# Opção 1 — header dedicado (recomendado)
x-api-key: SUA_CHAVE_AQUI

# Opção 2 — Authorization Bearer
Authorization: Bearer SUA_CHAVE_AQUI

2. Endpoints

POSThttps://seu-dominio.com/api/v1/pixCriar cobrança PIX

GEThttps://seu-dominio.com/api/v1/pix/{transaction_id}Consultar status de uma cobrança

Limite: 20 requisições por minuto por chave de API.

3. Criar Cobrança PIX

POSThttps://seu-dominio.com/api/v1/pix

Parâmetros (Body JSON)

Campo	Tipo	Obrigatório	Descrição
amount	integer	Sim	Valor em centavos. Ex: 1000 = R$ 10,00. Mínimo: 100
description	string	Não	Descrição da cobrança (aparece no extrato)
customer.name	string	Sim	Nome completo do pagador
customer.email	string	Sim	E-mail do pagador
customer.cpf	string	Sim	CPF do pagador (somente números)
customer.phone	string	Não	Telefone com DDD (somente números)

Exemplos de código

Node.js

const axios = require('axios');

const response = await axios.post('https://seu-dominio.com/api/v1/pix', {
  amount: 2990,           // R$ 29,90 em centavos
  description: 'Pedido #42',
  customer: {
    name: 'Maria Souza',
    email: 'maria@email.com',
    cpf: '12345678900',
    phone: '11999999999'  // opcional
  }
}, {
  headers: {
    'x-api-key': 'SUA_CHAVE_AQUI',
    'Content-Type': 'application/json'
  }
});

const { transaction_id, pix } = response.data;
console.log('QR Code texto:', pix.qr_code);
console.log('QR Code imagem:', pix.qr_code_url);
console.log('Expira em:', pix.expires_at);

Resposta de sucesso 200

json

{
  "success": true,
  "transaction_id": "8a40135d-e021-456d-a94f-3122c525d5d9",
  "status": "pending",
  "amount": 2990,
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_url": "https://api.pagar.me/.../qrcode",
    "expires_at": "2026-04-01T13:00:00.000Z"
  }
}

4. Consultar Status

GEThttps://seu-dominio.com/api/v1/pix/{transaction_id}

Use o transaction_id retornado na criação para consultar o status atual da cobrança.

Node.js

const axios = require('axios');

const { data } = await axios.get(
  `https://seu-dominio.com/api/v1/pix/${transactionId}`,
  { headers: { 'x-api-key': 'SUA_CHAVE_AQUI' } }
);

if (data.status === 'paid') {
  console.log('Pagamento confirmado!');
}

Resposta

json

{
  "success": true,
  "transaction_id": "8a40135d-e021-456d-a94f-3122c525d5d9",
  "status": "paid",
  "amount": 2990,
  "payment_method": "pix",
  "customer": { "name": "Maria Souza", "email": "maria@email.com" },
  "pix": {
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_code_url": "https://api.pagar.me/.../qrcode",
    "expires_at": "2026-04-01T13:00:00.000Z"
  },
  "created_at": "2026-04-01T12:00:00.000Z"
}

5. Valores de Status

pending — Aguardando pagamento

QR Code gerado, aguardando o pagador escanear e pagar.

paid — Pago

Pagamento confirmado. Você pode liberar o produto/serviço.

failed — Falhou

Pagamento recusado ou erro no processamento.

expired — Expirado

O QR Code venceu sem pagamento (geralmente 30 minutos).

6. Polling de Status

Se você não usa webhooks, pode verificar o status periodicamente. Recomendamos intervalos de 5 segundos e timeout de 10 minutos.

Prefira webhooks quando possível — são mais eficientes e instantâneos.

Node.js

async function aguardarPagamento(transactionId, timeoutMs = 600_000) {
  const inicio = Date.now();
  while (Date.now() - inicio < timeoutMs) {
    const { data } = await axios.get(
      `https://seu-dominio.com/api/v1/pix/${transactionId}`,
      { headers: { 'x-api-key': 'SUA_CHAVE_AQUI' } }
    );

    if (data.status === 'paid')    return { pago: true };
    if (data.status === 'failed')  return { pago: false, motivo: 'falhou' };
    if (data.status === 'expired') return { pago: false, motivo: 'expirado' };

    await new Promise(r => setTimeout(r, 5000)); // aguarda 5s
  }
  return { pago: false, motivo: 'timeout' };
}

7. Exibir QR Code

A API retorna dois campos para exibir o QR Code:

pix.qr_code — texto do código PIX (copia e cola)
pix.qr_code_url — URL de imagem PNG do QR Code
pix.expires_at — data/hora de expiração (ISO 8601)

HTML

<!-- Exibir QR Code como imagem -->
<img src="{qr_code_url}" alt="QR Code Pix" width="250" height="250" />

<!-- Copiar código Pix (copia e cola) -->
<input id="pix-code" type="text" value="{qr_code}" readonly />
<button onclick="navigator.clipboard.writeText(document.getElementById('pix-code').value)">
  Copiar código
</button>

8. Webhooks

Configure uma URL no painel em Integrações → API Pix → Webhook da API Pix. Quando o status de uma cobrança mudar, faremos um POST automático para essa URL com o payload abaixo.

Eventos disponíveis

Evento	Quando ocorre
order.paid	Pagamento confirmado
order.failed	Pagamento recusado ou falhou
order.refunded	Pagamento estornado
order.chargeback	Chargeback registrado

Payload recebido

json

{
  "event": "order.paid",
  "data": {
    "id": "8a40135d-e021-456d-a94f-3122c525d5d9",
    "transaction_id": "8a40135d-e021-456d-a94f-3122c525d5d9",
    "status": "paid",
    "amount": 2990,
    "amount_display": "29.90",
    "payment_method": "pix",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "cpf": "12345678900",
      "phone": "11999999999"
    },
    "created_at": "2026-04-01T12:00:00.000Z",
    "updated_at": "2026-04-01T12:04:33.000Z"
  }
}

Como receber no seu servidor

Node.js (Express)

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/pix', (req, res) => {
  const { event, data } = req.body;

  if (event === 'order.paid') {
    console.log('Pago! ID:', data.id, 'Valor:', data.amount_display);
    // liberar acesso, enviar e-mail, atualizar banco...
  }

  if (event === 'order.failed') {
    console.log('Falhou:', data.id);
  }

  res.sendStatus(200); // sempre responda 200
});

Seu endpoint de webhook deve sempre responder HTTP 200, mesmo em caso de erro interno. Caso contrário, o sistema tentará reenviar o evento.

9. Códigos de Erro

HTTP	Código	Descrição
400	BAD_REQUEST	Parâmetros inválidos (amount < 100, customer incompleto, etc.)
401	UNAUTHORIZED	Chave de API ausente ou inválida
403	FORBIDDEN	Chave de API inativa
404	NOT_FOUND	Transação não encontrada
429	RATE_LIMITED	Limite de 20 req/min excedido. Aguarde 1 minuto.
500	INTERNAL	Erro interno. Verifique os logs e configuração do recebedor.

Formato da resposta de erro

json

{
  "error": "Descrição do erro",
  "status": "error"
}

10. Fluxo Completo de Integração

Gerar API Key

No painel, vá em Integrações → API Pix e gere sua chave.

Criar cobrança

Faça um POST para /api/v1/pix com o valor e dados do cliente. Guarde o transaction_id retornado.

Exibir QR Code

Mostre o qr_code_url como imagem e o qr_code como texto copiável para o usuário.

Aguardar pagamento

Use polling (GET /api/v1/pix/{id} a cada 5s) ou configure um webhook para ser notificado automaticamente.

Confirmar e liberar

Quando status === "paid", libere o produto, acesso ou serviço para o cliente.