Criar uma cobrança

Cria a cobrança de um produto e devolve o que o pagador precisa para pagar. O valor sai do produto, nunca do corpo.

POSThttps://api.navenaut.com/v1/charges

Autenticação

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

O escopo exigido é charges:write. 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

Cabeçalho

Nome	Tipo	Descrição
`idempotency-key`obrigatório	texto	OBRIGATÓRIA. A chamada sem ela é recusada com 400 antes de qualquer escrita. Ela é escopada pela chave de API que a apresentou: o mesmo valor, vindo de duas chaves de API diferentes, abre duas reservas distintas: duas integrações não colidem por escolher a mesma string. Aceita no máximo 41 caracteres, e um UUID cabe; a maior é recusada com 400 antes de qualquer escrita.

Corpo da requisição

application/json.

Campo	Tipo	Descrição
`affiliateRef`	texto	—
`buyer`obrigatório	objeto	Quem está comprando. O documento é guardado para conciliação e nunca volta inteiro.
`card`	objeto	O cartão, e só o blob cifrado dele. Quem cifra é o SDK do adquirente, no navegador do comprador, com a chave pública do adquirente: o seu servidor recebe o blob pronto e só o repassa aqui. Número, código de segurança, validade e titular não têm campo nesta API e não devem passar pelo seu servidor. Na venda parcelada, mande também a bandeira: é ela que indexa a tabela de parcelamento do adquirente.
`currency`	um de: `BRL`, `USD`, `EUR`	A moeda da cobrança. Opcional: ausente, vale a moeda do produto. Se vier, precisa ser exatamente a do produto (`BRL`, `USD` ou `EUR`, em maiúsculas); outra moeda é recusada com 400 `V1_CHARGE_CURRENCY_MISMATCH`, antes de qualquer escrita. A cobrança nunca sai em moeda diferente da que você pediu.
`installments`	inteiro	Quantidade de parcelas, só para cartão.
`method`obrigatório	um de: `pix`, `card`, `boleto`, `wallet`	Como a cobrança vai ser paga. O produto declara os métodos que aceita.
`productRef`obrigatório	texto	A referência pública do produto a cobrar.

{
  "affiliateRef": "referencia-de-exemplo",
  "buyer": {
    "document": "000.000.000-00",
    "email": "comprador@exemplo.com.br",
    "name": "Loja Exemplo",
    "phone": "+55 11 90000-0000"
  },
  "card": {
    "authenticationId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
    "brand": "exemplo",
    "encrypted": "exemplo"
  },
  "currency": "BRL",
  "installments": 1,
  "method": "pix",
  "productRef": "referencia-de-exemplo"
}

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"
}

400 · requisição inválida

Falta a chave de idempotência ou ela passa de 41 caracteres, o cartão veio sem o blob cifrado, a moeda do corpo não é a do produto, o método não é aceito, ou a cobrança foi recusada na origem.

401 · não autenticado

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

402 · pagamento não autorizado

O emissor não autorizou o cartão. A cobrança existe e segue pendente; nada foi capturado.

404 · não encontrado

O produto não existe, não está publicado, ou não é desta conta.

409 · conflito

A mesma chave de idempotência já está em uso nesta conta, ou já foi usada com um corpo diferente.

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, e nenhuma cobrança foi criada.

Erros desta rota

Status	Código	Quando	O que fazer
400	`V1_IDEMPOTENCY_KEY_REQUIRED`	Chamada sem `idempotency-key`.	Gere um UUID por tentativa de criar e envie no cabeçalho.
400	`V1_IDEMPOTENCY_KEY_TOO_LONG`	O cabeçalho `idempotency-key` passa de 41 caracteres. A recusa vem antes de qualquer escrita: nada foi reservado e nenhuma cobrança existe.	Reenvie com uma chave de até 41 caracteres. Um UUID cabe.
400	`V1_CHARGE_CARD_DATA_MISSING`	O método é cartão e o blob cifrado não veio, ou a venda é parcelada e a bandeira não veio. A recusa vem antes de qualquer escrita: nada foi reservado e nenhuma cobrança existe.	Cifre o cartão com o SDK do adquirente no navegador do comprador e reenvie com a mesma chave de idempotência. Na venda parcelada, mande a bandeira junto.
402	`V1_CHARGE_CARD_DECLINED`	O emissor não autorizou o cartão. A cobrança foi criada e segue pendente, e nenhum valor foi capturado. Repetir a mesma chave devolve esta mesma recusa.	Mostre a recusa ao pagador e peça outro cartão. O cartão novo é uma cobrança nova, com chave de idempotência nova.
400	`V1_CHARGE_CURRENCY_MISMATCH`	O campo `currency` do corpo não é a moeda do produto. A recusa vem antes de qualquer escrita: nada foi reservado, nenhuma cobrança existe e o saldo não se mexe.	Omita o campo `currency` ou envie a moeda do produto, em maiúsculas. Pode reenviar com a mesma chave de idempotência.
400	`V1_CHARGE_REFUSED`	A cobrança foi recusada na origem.	Mostre a recusa ao pagador; não repita com a mesma chave.
401	`UNAUTHORIZED`	Chave ausente ou inválida.	Confira o ambiente da chave e o escopo exigido.
404	`V1_CHARGE_NOT_FOUND`	Produto inexistente, não publicado ou de outra conta.	Confira o `productRef` no painel.
409	`V1_CHARGE_IN_PROGRESS`	A mesma chave ainda está sendo processada.	Aguarde e repita com a mesma chave.
409	`V1_IDEMPOTENCY_BODY_MISMATCH`	Mesma chave, corpo diferente.	Use uma chave nova para um corpo novo.
429	`API_KEY_RATE_LIMITED`	Excesso de chamadas para esta chave.	Respeite `Retry-After`.
503	`SANDBOX_UNAVAILABLE`	Sandbox não provisionado.	Use uma chave de produção ou aguarde o provisionamento.

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.

Próximo passo

Consultar a cobrança