Consultar uma cobrança

Devolve o estado atual de uma cobrança criada por esta API. É a rota que substitui a espera pelo webhook quando você precisa perguntar.

GEThttps://api.navenaut.com/v1/charges/{reference}

Autenticação

Chave de API no cabeçalho Authorization: Bearer naut_live_….

O escopo exigido é charges:read. Uma credencial sem esse escopo recusa com 401, o mesmo código de uma credencial inválida: a recusa não diz se ela existe.

Exige chave de API no cabeçalho. A família da chave decide contra qual ambiente ela escreve, e a chave não fabrica sessão: ela não alcança nenhuma rota fora de /v1.

Parâmetros

Caminho

Nome	Tipo	Descrição
`reference`obrigatório	texto (uuid)	A referência da cobrança, devolvida na criação.

Respostas

200 · sucesso

{
  "amountCents": 129900,
  "chargeId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
  "createdAt": "2026-01-15T12:00:00.000Z",
  "currency": "BRL",
  "method": "pix",
  "payable": {
    "emv": "exemplo",
    "kind": "pix",
    "qrImageUrl": "https://loja.exemplo.com.br/webhooks"
  },
  "refundedAmountCents": 129900,
  "status": "pending"
}

401 · não autenticado

A chave de API não foi apresentada, ou não vale.

404 · não encontrado

A referência não existe, ou não é desta conta.

429 · excesso de chamadas

Excesso de chamadas para esta chave.

503 · indisponível

A sua chave é de sandbox e o ambiente de teste desta instalação não está provisionado. Chaves de produção seguem funcionando; repetir a chamada não resolve.

Erros desta rota

Status	Código	Quando	O que fazer
401	`UNAUTHORIZED`	A chave de API não veio no cabeçalho, veio malformada, foi revogada, ou não pertence a esta instalação.	Confira o cabeçalho e o prefixo da chave. Repetir com a mesma chave devolve sempre 401, e nenhuma chamada desta superfície funciona sem uma chave válida.
404	`V1_CHARGE_NOT_FOUND`	A referência não existe nesta instalação, ou existe e pertence a outra conta. As duas causas respondem igual de propósito: distinguir revelaria a existência de cobrança alheia.	Confira a referência que a criação da cobrança devolveu. Repetir não muda o resultado.
429	`API_KEY_RATE_LIMITED`	Esta chave passou do teto de chamadas da janela corrente. É limite de FREQUÊNCIA, não de valor.	Espere a janela virar e reenvie, espaçando as chamadas. Consultar mais vezes não adianta o pagamento: o webhook avisa quando ele acontece.
503	`SANDBOX_UNAVAILABLE`	A sua chave é da família de teste e esta instalação não tem o ambiente de teste provisionado. Chaves de produção seguem funcionando normalmente.	Use uma chave de produção, ou peça o provisionamento do ambiente de teste. Repetir com a chave de teste não resolve, e nenhuma cobrança de teste existe para consultar.

Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.