Referência

Referência de endpoints

Todos os endpoints, campos de entrada e campos de resposta.

Todos os endpoints da API v1 em uma página. Base: https://novexfinance.com.br/api/v1. Todos exigem o header Authorization: Bearer <chave>.

Índice

Método	Endpoint	O que faz
`GET`	`/v1/ping`	Verifica a chave.
`GET`	`/v1/account`	Dados da conta.
`POST`	`/v1/charges`	Cria cobrança PIX, boleto ou cartão.
`GET`	`/v1/charges`	Lista cobranças.
`GET`	`/v1/charges/{id}`	Consulta uma cobrança.
`POST`	`/v1/checkouts`	Cria checkout hospedado.
`GET`	`/v1/checkouts`	Lista checkouts.
`GET`	`/v1/checkouts/{id}`	Consulta um checkout.
`POST`	`/v1/checkouts/{id}/expire`	Encerra um checkout.
`GET`	`/v1/balance`	Saldo disponível e a liquidar.
`POST`	`/v1/withdrawals`	Solicita saque via PIX.
`GET`	`/v1/withdrawals`	Lista saques.
`GET`	`/v1/withdrawals/{id}`	Consulta um saque.
`POST`	`/v1/webhooks`	Cadastra endpoint de webhook.
`GET`	`/v1/webhooks`	Lista endpoints.
`DELETE`	`/v1/webhooks/{id}`	Remove endpoint.
`GET`	`/v1/webhook-deliveries`	Histórico de entregas.

Conta

Verificar a chave

GET/v1/ping

Sem parâmetros. Devolve authenticated, account_id, server_time e api_version.

Dados da conta

GET/v1/account

Resposta 200

{
  "object": "account",
  "id": "acct_42",
  "name": "Loja Exemplo LTDA",
  "email": "contato@exemplo.com.br",
  "document": "11222333000181",
  "person_type": "pj",
  "status": "active",
  "verification_status": "approved",
  "can_transact": true
}

can_transact resume o que importa: false significa que cobranças e saques vão responder kyc_required ou account_inactive.

Cobranças

Criar cobrança

POST/v1/charges

Aceita Idempotency-Key. Guias por meio: PIX, boleto, cartão.

Campo	Tipo	Descrição
`payment_method`obrigatório	string	`pix`, `boleto` ou `credit_card`.
`amount`obrigatório	inteiro	Centavos. Mínimo `500`.
`description`opcional	string	Até 200 caracteres. Padrão: `"Cobrança"`.
`reference`opcional	string	Seu identificador, até 191 caracteres.
`metadata`opcional	objeto	Até 30 chaves; valores de texto, número ou booleano.
`customer.name`obrigatório	string	Mínimo 3 caracteres.
`customer.email`obrigatório	string	E-mail válido.
`customer.phone`obrigatório	string	DDD + número (10 ou 11 dígitos).
`customer.document`obrigatório	string	CPF ou CNPJ, com dígito verificador válido.
`installments`opcional	inteiro	Só para cartão. De 1 a 12. Padrão: 1.
`card.number`opcional	string	Só para cartão direto (requer PCI-DSS).
`card.holder_name`opcional	string	Só para cartão direto.
`card.holder_document`opcional	string	Só para cartão direto.
`card.expiration_month`opcional	inteiro	Só para cartão direto. 1 a 12.
`card.expiration_year`opcional	inteiro	Só para cartão direto. 2 dígitos.
`card.cvv`opcional	string	Só para cartão direto. 3 ou 4 dígitos.

Objeto charge

Campo da resposta	Tipo	Descrição
`id`opcional	string	ID da cobrança, prefixo `ch_`.
`status`opcional	string	`pending`, `processing`, `authorized`, `paid`, `failed`, `refused`, `refunded`, `chargeback`, `disputed`, `blocked`.
`amount`opcional	inteiro	Valor bruto em centavos.
`currency`opcional	string	Sempre `BRL`.
`payment_method`opcional	string	`pix`, `boleto` ou `credit_card`.
`fee_amount`opcional	inteiro	Taxa em centavos. `null` enquanto não pago.
`net_amount`opcional	inteiro	Líquido em centavos (bruto − taxa).
`available_at`opcional	data	Quando o valor fica disponível para saque.
`paid_at`opcional	data	Quando o pagamento foi confirmado.
`pix.qr_code`opcional	string	Copia e cola (EMV). Só em PIX.
`pix.expires_at`opcional	data	Validade do código. Só em PIX.
`boleto.digitable_line`opcional	string	Linha digitável (47 dígitos). Só em boleto.
`boleto.barcode`opcional	string	Código de barras (44 dígitos). Só em boleto.
`boleto.expires_at`opcional	data	Vencimento. Só em boleto.
`card.brand`opcional	string	Bandeira. Só em cartão.
`card.last4`opcional	string	Últimos 4 dígitos. Só em cartão.
`card.installments`opcional	inteiro	Parcelas. Só em cartão.

Listar cobranças

GET/v1/charges

Parâmetro	Tipo	Descrição
`status`opcional	string	Filtra por status público.
`payment_method`opcional	string	`pix`, `boleto` ou `credit_card`.
`reference`opcional	string	Sua referência, exata.
`limit`opcional	inteiro	1 a 100. Padrão: 25.
`offset`opcional	inteiro	Padrão: 0.

Consultar cobrança

GET/v1/charges/{id}

Reconcilia com o processador quando o status ainda não é final. Devolve o objeto charge.

Checkouts

Criar checkout

POST/v1/checkouts

Aceita Idempotency-Key. Guia completo em Checkout hospedado.

Campo	Tipo	Descrição
`title`obrigatório	string	Nome do que está sendo cobrado, até 160 caracteres.
`amount`obrigatório	inteiro	Centavos. Mínimo `500`.
`description`opcional	string	Até 500 caracteres.
`payment_methods`opcional	lista	Subconjunto de `["pix","credit_card","boleto"]`. Padrão: os três.
`reference`opcional	string	Seu identificador.
`return_url`opcional	string	HTTPS. Para onde o cliente volta após pagar.
`single_use`opcional	booleano	Padrão `true`.
`expires_in`opcional	inteiro	Segundos, até 7776000 (90 dias). `0` desliga.
`metadata`opcional	objeto	Até 30 chaves.

Listar checkouts

GET/v1/checkouts

Aceita limit e offset.

Consultar checkout

GET/v1/checkouts/{id}

Traz charge preenchido quando já houve pagamento.

Encerrar checkout

POST/v1/checkouts/{id}/expire

Sem corpo. Devolve o checkout com status: "expired". Um checkout já pago responde 409 checkout_already_paid.

Saldo

GET/v1/balance

Campo da resposta	Tipo	Descrição
`available`opcional	inteiro	Liquidado e livre para saque, em centavos.
`pending`opcional	inteiro	Pago mas ainda em prazo de liquidação.
`total`opcional	inteiro	Soma dos dois.
`as_of`opcional	data	Momento do cálculo.

Saques

Solicitar saque

POST/v1/withdrawals

Aceita Idempotency-Key. Guia em Saldo e saques.

Campo	Tipo	Descrição
`amount`obrigatório	inteiro	Valor a receber, em centavos. Mínimo `500`. A taxa é debitada por cima.
`pix_key_type`obrigatório	string	`cpf`, `cnpj`, `phone`, `email` ou `evp`.
`pix_key`obrigatório	string	A chave PIX de destino.
`reference`opcional	string	Seu identificador.

Campo da resposta	Tipo	Descrição
`id`opcional	string	ID do saque, prefixo `wd_`.
`status`opcional	string	`pending`, `approved`, `processing`, `paid`, `rejected`, `failed`, `refunded`, `canceled`, `blocked`.
`amount`opcional	inteiro	Valor que chega no destino.
`fee_amount`opcional	inteiro	Taxa cobrada.
`total_debited`opcional	inteiro	Valor + taxa. É o que sai do seu saldo.
`pix_key`opcional	string	Chave mascarada.
`end_to_end_id`opcional	string	Identificador da transferência PIX, quando concluída.
`processed_at`opcional	data	Quando foi processado.

Listar saques

GET/v1/withdrawals

Aceita limit e offset.

Consultar saque

GET/v1/withdrawals/{id}

Webhooks

Cadastrar endpoint

POST/v1/webhooks

Campo	Tipo	Descrição
`url`obrigatório	string	HTTPS. Recebe os eventos.
`events`opcional	string	`all` (padrão), `transaction` ou `withdrawal`.

A resposta 201 inclui secret — só nesta chamada. Guia em Webhooks.

Listar endpoints

GET/v1/webhooks

Não devolve o secret. Traz consecutive_failures e last_status_code para diagnóstico.

Remover endpoint

DELETE/v1/webhooks/{id}

Histórico de entregas

GET/v1/webhook-deliveries

Cada tentativa de entrega, com o status HTTP que o seu servidor respondeu. Aceita limit e offset.

Headers

Header	Direção	Para quê
`Authorization`	Envio	`Bearer <chave>`. Obrigatório em todos os endpoints.
`Content-Type`	Envio	`application/json` em POST.
`Idempotency-Key`	Envio	Evita duplicidade em retentativas de POST.
`X-Request-Id`	Resposta	ID da requisição, para suporte.
`Idempotent-Replay`	Resposta	`true` quando a resposta é a repetição de uma anterior.
`Retry-After`	Resposta	Segundos a esperar, em `429` e `503`.
`Allow`	Resposta	Métodos aceitos, em `405`.