Acompanhar

Consultas e listagens

Consultar uma cobrança, listar com filtros e paginar resultados.

Como consultar uma cobrança específica, listar com filtros e paginar. Para saber de pagamentos no momento em que acontecem, use webhooks — esta página é para consulta sob demanda e conciliação.

Consultar uma cobrança

GET/v1/charges/{id}

Requisição

curl https://novexfinance.com.br/api/v1/charges/ch_9f2a71c4e8b35d06a147 \
  -H "Authorization: Bearer $NOVEX_API_KEY"

$charge = $novex->get('/charges/ch_9f2a71c4e8b35d06a147');

if ($charge['status'] === 'paid') {
    // liberar o pedido
}

const charge = await novex.get('/charges/ch_9f2a71c4e8b35d06a147');

if (charge.status === 'paid') {
  // liberar o pedido
}

charge = novex.get('/charges/ch_9f2a71c4e8b35d06a147')

if charge['status'] == 'paid':
    # liberar o pedido

Esta consulta reconcilia: se a cobrança ainda não estiver num estado final, sincronizamos com o processador antes de responder. Ou seja, o que ela devolve é o estado real naquele instante — mesmo que um webhook tenha se perdido no caminho.

Cobrança inexistente, ou de outra conta, responde 404 com resource_not_found.

Listar cobranças

GET/v1/charges

Exemplos

# últimas 25 (padrão)
curl https://novexfinance.com.br/api/v1/charges \
  -H "Authorization: Bearer $NOVEX_API_KEY"

# só as pagas, 50 por página
curl "https://novexfinance.com.br/api/v1/charges?status=paid&limit=50" \
  -H "Authorization: Bearer $NOVEX_API_KEY"

# só PIX pagos
curl "https://novexfinance.com.br/api/v1/charges?status=paid&payment_method=pix" \
  -H "Authorization: Bearer $NOVEX_API_KEY"

# pela sua referência
curl "https://novexfinance.com.br/api/v1/charges?reference=48219" \
  -H "Authorization: Bearer $NOVEX_API_KEY"

Filtros

Parâmetro	Tipo	Descrição
`status`opcional	string	`pending`, `processing`, `authorized`, `paid`, `failed`, `refused`, `refunded`, `chargeback` ou `disputed`.
`payment_method`opcional	string	`pix`, `boleto` ou `credit_card`.
`reference`opcional	string	Sua referência, exata. Útil para achar a cobrança de um pedido específico.
`limit`opcional	inteiro	De 1 a 100. Padrão: 25.
`offset`opcional	inteiro	Quantos registros pular. Padrão: 0.

Resposta 200

{
  "object": "list",
  "data": [
    {
      "object": "charge",
      "id": "ch_9f2a71c4e8b35d06a147",
      "status": "paid",
      "amount": 12990,
      "payment_method": "pix",
      "reference": "48219",
      "net_amount": 12341,
      "paid_at": "2026-08-07T14:35:02-03:00"
    },
    // … mais cobranças
  ],
  "has_more": true,
  "limit": 25,
  "offset": 0
}

Percorrer todas as páginas

Use has_more como condição de parada:

Paginação completa

$offset = 0;
$todas = [];

do {
    $page = $novex->get('/charges', [
        'status' => 'paid',
        'limit'  => 100,
        'offset' => $offset,
    ]);

    $todas = array_merge($todas, $page['data']);
    $offset += 100;
} while ($page['has_more']);

let offset = 0;
const todas = [];
let page;

do {
  page = await novex.get('/charges', {
    status: 'paid',
    limit: 100,
    offset,
  });

  todas.push(...page.data);
  offset += 100;
} while (page.has_more);

offset, todas = 0, []

while True:
    page = novex.get('/charges', params={
        'status': 'paid',
        'limit': 100,
        'offset': offset,
    })

    todas.extend(page['data'])
    if not page['has_more']:
        break
    offset += 100

Respeite o limite de 300 requisições por minuto ao varrer o histórico. Para conciliação diária, filtrar por status=paid e parar quando alcançar a data já processada é bem mais econômico do que baixar tudo toda vez.

Consultar em laço não substitui webhook

É tentador perguntar "já pagou?" a cada poucos segundos. Não faça isso em produção:

Atrasa a confirmação. Com consulta a cada 30s, o cliente espera até meio minuto por um PIX que já entrou.
Não escala. Mil cobranças abertas viram milhares de requisições por minuto — e você bate no limite de uso.
Não é preciso. Estados que não são finais podem mudar entre uma consulta e outra.

Cadastre um webhook e a confirmação chega em menos de um segundo, sem você pedir. Guarde a consulta para os casos certos: conciliação, tela de detalhe do pedido e reprocessamento de um webhook que o seu servidor não conseguiu receber.

Outras consultas

Endpoint	Devolve
`GET /v1/checkouts`	Checkouts hospedados criados pela API.
`GET /v1/checkouts/{id}`	Um checkout, com a cobrança gerada quando já foi pago.
`GET /v1/withdrawals`	Saques solicitados.
`GET /v1/balance`	Saldo disponível e a liquidar.
`GET /v1/webhook-deliveries`	Histórico de entregas de webhook, para depurar.