Comece por aqui

Convenções

Valores em centavos, datas, paginação, idempotência e limites de uso.

Regras que valem para toda a API. Ler esta página uma vez evita a maioria dos erros de integração.

Dinheiro é sempre em centavos

Todo valor monetário é um número inteiro em centavos, na moeda BRL. Nunca use decimais.

Você quer cobrar	Envie	Não envie
R$ 5,00	`500`	`5.00` · `"5,00"`
R$ 19,90	`1990`	`19.9`
R$ 129,90	`12990`	`129.90`
R$ 1.500,00	`150000`	`1500`

A API recusa valores com ponto ou vírgula, com validation_error. É proposital: 19.90 não tem representação exata em ponto flutuante, e um centavo perdido em arredondamento vira divergência de conciliação no fim do mês.

Valor mínimo por cobrança: 500 (R$ 5,00). Se a sua conta tiver limite por transação ou limite diário configurado, valores acima dele respondem 403 com amount_limit_exceeded ou daily_limit_exceeded.

Datas

Todas as datas saem em ISO-8601 com fuso de Brasília (UTC−03:00):

Formato

{
  "created_at": "2026-08-07T14:32:10-03:00",
  "paid_at": "2026-08-07T14:35:02-03:00",
  "available_at": "2026-09-06T14:35:02-03:00"
}

Campos de data ainda não preenchidos vêm como null — uma cobrança pendente tem paid_at: null.

Idempotência

Timeout de rede não diz se a cobrança foi criada. Sem proteção, sua retentativa cria uma segunda cobrança real e o cliente é cobrado duas vezes.

Envie o header Idempotency-Key em todo POST que movimenta dinheiro. Se a mesma chave chegar de novo, devolvemos a resposta original — sem criar nada:

Requisição

curl -X POST https://novexfinance.com.br/api/v1/charges \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Idempotency-Key: pedido-48219" \
  -H "Content-Type: application/json" \
  -d '{ … }'

A resposta repetida vem com o header Idempotent-Replay: true, para você saber que não foi uma criação nova.

Situação	Resposta
Chave nova	Processa normalmente.
Mesma chave, mesmo corpo, já concluída	Devolve a resposta original, idêntica.
Mesma chave, mesmo corpo, ainda processando	`409 idempotency_key_in_progress`. Aguarde e consulte antes de repetir.
Mesma chave, corpo diferente	`422 idempotency_key_reused`. Use uma chave nova.

Como escolher a chave: use algo que identifique a operação, não a tentativa. O número do pedido é ideal — pedido-48219. Um UUID gerado a cada retentativa não protege nada, porque cada tentativa teria uma chave diferente.

As chaves valem por 24 horas. Respostas 5xx e 429 não são gravadas: são falhas transitórias e a retentativa precisa poder tentar de verdade.

Paginação

Listagens aceitam limit (1 a 100, padrão 25) e offset:

Requisição

curl "https://novexfinance.com.br/api/v1/charges?limit=50&offset=100" \
  -H "Authorization: Bearer $NOVEX_API_KEY"

Resposta

{
  "object": "list",
  "data": [
    // … até 50 cobranças
  ],
  "has_more": true,
  "limit": 50,
  "offset": 100
}

Use has_more para saber quando parar — é mais confiável do que comparar o tamanho de data com o limit. Os resultados vêm sempre do mais recente para o mais antigo.

Limites de uso

Escopo	Limite
Requisições por chave	300 por minuto
Escritas (POST/DELETE) por chave	60 por minuto
Requisições sem autenticação, por IP	20 por minuto

Ao estourar, a resposta é 429 com rate_limit_exceeded e o header Retry-After em segundos. Respeite esse valor — retentar antes só consome a cota da janela seguinte.

Se você está batendo no limite consultando cobranças em laço, o problema não é o limite: é a estratégia. Troque a consulta repetida por webhooks e o volume cai para quase zero.

Identificadores

Cada objeto tem um ID com prefixo que diz o que ele é. Guarde-os como texto — nunca como número:

Prefixo	Objeto	Exemplo
`ch_`	Cobrança	`ch_9f2a71c4e8b35d06a147`
`chk_`	Checkout hospedado	`chk_4b81de07a2f6c395e0d8`
`wd_`	Saque	`wd_1c7fa03e95b846d2f0ba`
`whe_`	Endpoint de webhook	`whe_12`
`evt_`	Evento de webhook	`evt_ac41f9b26d80375e1c4a`
`acct_`	Conta	`acct_42`

Sua própria referência

O campo reference guarda o identificador que faz sentido no seu sistema — número do pedido, ID da fatura. Ele volta em toda consulta e em todo webhook, e serve de filtro:

Buscar pela sua referência

curl "https://novexfinance.com.br/api/v1/charges?reference=48219" \
  -H "Authorization: Bearer $NOVEX_API_KEY"

Para dados extras, use metadata: um objeto livre de até 30 chaves, com valores de texto, número ou booleano. Ele é devolvido intacto em consultas e webhooks — nós não interpretamos nada dele.

Exemplo

{
  "reference": "48219",
  "metadata": {
    "canal": "app-ios",
    "vendedor_id": 77,
    "primeira_compra": true
  }
}

Rastrear uma requisição

Toda resposta traz o header X-Request-Id, e todo erro repete esse valor em error.request_id. Registre-o no seu log: com ele, o suporte encontra exatamente a requisição que falhou.