Cobranças

Crie e gerencie cobranças Pix. Cada cobrança gera um QR Code e um código copia e cola para pagamento.

Criar cobrança

POST

/v1/charges

Auth

Cria uma nova cobrança Pix. Retorna o QR Code e código copia e cola.

Body (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor em reais (mín. 0.01)
`description`	string	Não	Descrição da cobrança
`externalId`	string	Não	ID externo para referência
`payerName`	string	Não	Nome do pagador
`payerEmail`	string	Não	Email do pagador
`payerDocument`	string	Não	CPF/CNPJ do pagador
`expiresIn`	integer	Não	Tempo de expiração em segundos (padrão: 3600)
`provider`	string	Não	Provedor Pix: 'woovi' ou 'abacatepay'

Exemplobash

curl -X POST https://api.pagniv.com/v1/charges \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "description": "Pedido #1234",
    "externalId": "pedido-1234",
    "payerName": "João Silva",
    "payerEmail": "[email protected]",
    "expiresIn": 1800
  }'

Resposta 201JSON

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

Listar cobranças

GET

/v1/charges

Auth

Retorna lista paginada de cobranças do merchant.

Query params

Parâmetro	Tipo	Obrigatório	Descrição
`status`	string	Não	Filtrar por status: PENDING, PAID, EXPIRED, CANCELLED, REFUNDED, DISPUTED
`page`	integer	Não	Página (padrão: 1)
`limit`	integer	Não	Itens por página (padrão: 20)

Exemplobash

curl https://api.pagniv.com/v1/charges?status=PAID&page=1&limit=10 \
  -H "Authorization: Bearer {token}"

Detalhar cobrança

GET

/v1/charges/{id}

Auth

Retorna detalhes de uma cobrança específica.

Cancelar cobrança

DELETE

/v1/charges/{id}

Auth

Cancela uma cobrança com status PENDING.

Resposta 200JSON

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CANCELLED"
  }
}

Status de cobrança

Status	Descrição
`PENDING`	Aguardando pagamento
`PAID`	Pagamento confirmado
`EXPIRED`	Expirada sem pagamento
`CANCELLED`	Cancelada pelo merchant
`REFUNDED`	Valor estornado
`DISPUTED`	Em disputa