Cobranças Pix

Crie, liste, cancele e estorne cobranças Pix com QR Code dinâmico.

Referência rápida

Quick start

Ciclo de vida da cobrança

Uma cobrança sempre começa como PENDING e segue um destes caminhos:

PENDING

Significado: Aguardando pagamento

Transição: → PAID, EXPIRED ou CANCELLED

PAID

Significado: Pagamento confirmado

Transição: → REFUNDED ou DISPUTED

EXPIRED

Significado: Expirou sem pagamento

Transição: Estado final

CANCELLED

Significado: Cancelada via API

Transição: Estado final

REFUNDED

Significado: Reembolsada ao pagador

Transição: Estado final

DISPUTED

Significado: Em disputa pelo pagador

Transição: → depende da resolução da disputa

Status	Significado	Transição
`PENDING`	Aguardando pagamento	→ PAID, EXPIRED ou CANCELLED
`PAID`	Pagamento confirmado	→ REFUNDED ou DISPUTED
`EXPIRED`	Expirou sem pagamento	Estado final
`CANCELLED`	Cancelada via API	Estado final
`REFUNDED`	Reembolsada ao pagador	Estado final
`DISPUTED`	Em disputa pelo pagador	→ depende da resolução da disputa

Crie uma cobrança Pix e receba o QR Code em uma única chamada. Valores sempre em centavos (15000 = R$ 150,00):

Criar cobrança

curl -X POST https://api.pagniv.com/v1/charges \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "description": "Pedido #1234"
  }'

Criar cobrança

Cria uma cobrança Pix e retorna o QR Code (imagem base64) e o código copia e cola. Os campos externalId, payerName e payerDocument são obrigatórios (PLD-FT + idempotência).

POST/v1/charges

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

Body (JSON)

amountnumberobrigatório

Valor em centavos (mín. 100 = R$ 1,00)

externalIdstringobrigatório

ID do pedido no seu sistema. Garante idempotência e conciliação 1:1. Obrigatório.

payerNamestringobrigatório

Nome do pagador. Obrigatório. Mantemos letras (com acento), números e espaços: pontuação é removida, então 'J.R. Silva' chega como 'JR Silva' e 'Dávila-Souza' como 'DávilaSouza'. Nome formado só de símbolos fica vazio e é recusado como ausente.

payerDocumentstringobrigatório

CPF/CNPJ do pagador. Obrigatório (PLD-FT).

descriptionstringopcional

Descrição da cobrança

payerEmailstringopcional

Email do pagador

expiresInintegeropcional

Expiração em segundos (padrão: 3600)

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor em centavos (mín. 100 = R$ 1,00)
`externalId`	string	Sim	ID do pedido no seu sistema. Garante idempotência e conciliação 1:1. Obrigatório.
`payerName`	string	Sim	Nome do pagador. Obrigatório. Mantemos letras (com acento), números e espaços: pontuação é removida, então 'J.R. Silva' chega como 'JR Silva' e 'Dávila-Souza' como 'DávilaSouza'. Nome formado só de símbolos fica vazio e é recusado como ausente.
`payerDocument`	string	Sim	CPF/CNPJ do pagador. Obrigatório (PLD-FT).
`description`	string	Não	Descrição da cobrança
`payerEmail`	string	Não	Email do pagador
`expiresIn`	integer	Não	Expiração em segundos (padrão: 3600)

/v1/charges

curl -X POST https://api.pagniv.com/v1/charges \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "externalId": "pedido-1234",
    "payerName": "Maria Silva",
    "payerDocument": "12345678900",
    "description": "Pedido #1234",
    "expiresIn": 1800
  }'

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "txid": "pagniv_abc123def456",
    "amount": 15000,
    "feeAmount": 99,
    "netAmount": 14901,
    "status": "PENDING",
    "qrCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeBase64": "data:image/png;base64,...",
    "expiresAt": "2026-01-15T11:30:00Z",
    "createdAt": "2026-01-15T11:00:00Z"
  }
}

O QR já vem pronto para exibir

qrCodeBase64 é sempre um data URI completo: use direto em <img src={data.qrCodeBase64}>, sem concatenar prefixo. qrCode é o copia e cola, para o botão de copiar. Em sandbox os dois vêm preenchidos do mesmo jeito que em produção, então a tela que você montar testando é a que vai para o ar.

Listar cobranças

Lista cobranças com filtros. Combine status, método de pagamento e período para encontrar o que precisa.

GET/v1/charges

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

Query params

statusstringopcional

PENDING, PAID, EXPIRED, CANCELLED, REFUNDED, DISPUTED

paymentMethodstringopcional

PIX, CARD ou BOLETO

startDateISO 8601opcional

Criadas a partir de

endDateISO 8601opcional

Criadas até

pageintegeropcional

Página (padrão: 1)

limitintegeropcional

Itens por página (padrão: 20, máx: 100)

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Não	PENDING, PAID, EXPIRED, CANCELLED, REFUNDED, DISPUTED
`paymentMethod`	string	Não	PIX, CARD ou BOLETO
`startDate`	ISO 8601	Não	Criadas a partir de
`endDate`	ISO 8601	Não	Criadas até
`page`	integer	Não	Página (padrão: 1)
`limit`	integer	Não	Itens por página (padrão: 20, máx: 100)

/v1/charges

curl "https://api.pagniv.com/v1/charges?status=PAID&page=1&limit=10" \
  -H "X-API-Key: sk_live_sua_chave"

{
  "success": true,
  "data": [
    {
      "id": "550e8400-...",
      "amount": 15000,
      "status": "PAID",
      "paymentMethod": "PIX",
      "createdAt": "2026-01-15T11:00:00Z"
    }
  ],
  "meta": { "total": 45, "page": 1, "limit": 10, "pages": 5 }
}

Detalhar cobrança

Use webhooks como fonte primária pra confirmar pagamentos. Esse endpoint serve como fallback: se sua aplicação não receber o webhook em tempo razoável, consulte o status aqui.

Retorna todos os dados de uma cobrança: status, valores, QR Code e dados do pagador.

GET/v1/charges/{id}

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

/v1/charges/{id}

curl "https://api.pagniv.com/v1/charges/{id}" \
  -H "X-API-Key: sk_live_sua_chave"

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "txid": "pagniv_abc123def456",
    "paymentMethod": "PIX",
    "amount": 15000,
    "feeAmount": 99,
    "netAmount": 14901,
    "status": "PENDING",
    "qrCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeBase64": "data:image/png;base64,...",
    "expiresAt": "2026-01-15T11:30:00Z",
    "createdAt": "2026-01-15T11:00:00Z"
  }
}

Link de pagamento (checkout)

Endpoint público (sem API Key). Retorna dados seguros para exibir na página de pagamento do seu cliente. O QR Code só aparece enquanto o status é PENDING.

GET/v1/charges/{id}/checkout

/v1/charges/{id}/checkout

curl "https://api.pagniv.com/v1/charges/{id}/checkout"

{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "amount": 15000,
    "status": "PENDING",
    "description": "Pedido #1234",
    "expiresAt": "2026-01-15T11:30:00Z",
    "paymentMethod": "PIX",
    "qrCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeBase64": "data:image/png;base64,...",
    "merchantName": "Loja Exemplo",
    "checkoutColor": "#01A77D"
  }
}

Cancelar cobrança

Cancela uma cobrança que ainda está PENDING. Se o pagamento chegar entre sua chamada e o cancelamento, a API retorna erro. Não há risco de cancelar cobrança paga.

DELETE/v1/charges/{id}

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

/v1/charges/{id}

curl -X DELETE "https://api.pagniv.com/v1/charges/{id}" \
  -H "X-API-Key: sk_live_sua_chave"

{
  "success": true,
  "data": { "message": "Cobrança cancelada com sucesso" }
}

Estornar cobrança

Estorna total ou parcialmente uma cobrança que está com status PAID. O valor é debitado do seu saldo disponível e devolvido ao pagador via Pix. Após o estorno, o status da cobrança passa a REFUNDED e o evento webhook charge.refunded é disparado.

Atenção: a capacidade de estorno depende do provedor adquirente vinculado à cobrança. Provedores que não suportam estorno via API retornam REFUND_NOT_SUPPORTED (HTTP 400).

Estorna cobrança paga. amount opcional em centavos (default = líquido total).

POST/v1/charges/{id}/refund

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

/v1/charges/{id}/refund

curl -X POST "https://api.pagniv.com/v1/charges/{id}/refund" \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "reason": "Cliente solicitou cancelamento"
  }'

{
  "success": true,
  "data": {
    "id": "ch_abc123",
    "status": "REFUNDED",
    "refundedAmount": 5000,
    "refundedAt": "2026-01-16T09:32:10Z",
    "refundReason": "Cliente solicitou cancelamento"
  }
}

Simular pagamento (sandbox)

Disponível somente em sandbox. Marca uma cobrança como PAID e dispara o webhook charge.paid configurado. Use para validar o seu handler de webhook antes de ir pra produção.

Simula o pagamento de uma cobrança sandbox e dispara o webhook charge.paid.

POST/v1/charges/{id}/simulate-payment

Autenticação

X-API-Keystringheaderobrigatório

Sua chave de API no header X-API-Key: sk_live_.... Gere em Dashboard → Integrações.

/v1/charges/{id}/simulate-payment

curl -X POST "https://api.pagniv.com/v1/charges/{id}/simulate-payment" \
  -H "X-API-Key: sk_sandbox_sua_chave"

{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "txid": "sandbox_abc123def456",
    "status": "PAID",
    "paidAt": "2026-01-15T11:05:00Z",
    "message": "Pagamento simulado. Webhook charge.paid foi disparado se houver webhook configurado."
  }
}