Acompanhar

Saldo e saques

Consultar o saldo disponível e transferir para uma chave PIX.

Consultar quanto você tem e transferir para uma chave PIX sua, direto pela API.

Consultar o saldo

GET/v1/balance

Requisição

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

$balance = $novex->get('/balance');

printf("Disponível: R$ %s\n", number_format($balance['available'] / 100, 2, ',', '.'));

const balance = await novex.get('/balance');

console.log((balance.available / 100).toLocaleString('pt-BR', {
  style: 'currency', currency: 'BRL',
}));

balance = novex.get('/balance')

print(f'Disponível: R$ {balance["available"] / 100:.2f}')

Resposta 200

{
  "object": "balance",
  "currency": "BRL",
  "available": 458720,
  "pending": 129900,
  "total": 588620,
  "as_of": "2026-08-07T14:32:10-03:00"
}

Campo	Tipo	Descrição
`available`opcional	inteiro	Já liquidado e livre para saque, em centavos.
`pending`opcional	inteiro	Pago pelo cliente, mas ainda dentro do prazo de liquidação. Vira `available` na data.
`total`opcional	inteiro	Soma dos dois.
`as_of`opcional	data	Momento em que o saldo foi calculado.

Prazos de liquidação

Meio	Fica disponível
PIX	Imediatamente após a confirmação.
Boleto	Imediatamente após a compensação — que já ocorreu antes de o status virar `paid`.
Cartão de crédito	D+30 corridos a partir da aprovação.

Cada cobrança traz o campo available_at com a data exata em que aquele valor específico entra no disponível.

O saldo já vem líquido: a taxa é descontada no momento do pagamento e congelada na cobrança. Os campos fee_amount e net_amount de cada cobrança mostram exatamente quanto foi cobrado e quanto entrou.

Solicitar um saque

POST/v1/withdrawals

Requisição

curl -X POST https://novexfinance.com.br/api/v1/withdrawals \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-2026-08-07-01" \
  -d '{
    "amount": 100000,
    "pix_key_type": "cnpj",
    "pix_key": "11222333000181",
    "reference": "saque-mensal-agosto"
  }'

$saque = $novex->post('/withdrawals', [
    'amount'       => 100000, // R$ 1.000,00
    'pix_key_type' => 'cnpj',
    'pix_key'      => '11222333000181',
    'reference'    => 'saque-mensal-agosto',
], 'saque-2026-08-07-01');

const saque = await novex.post('/withdrawals', {
  amount: 100000, // R$ 1.000,00
  pix_key_type: 'cnpj',
  pix_key: '11222333000181',
  reference: 'saque-mensal-agosto',
}, { idempotencyKey: 'saque-2026-08-07-01' });

saque = novex.post('/withdrawals', {
    'amount': 100000,  # R$ 1.000,00
    'pix_key_type': 'cnpj',
    'pix_key': '11222333000181',
    'reference': 'saque-mensal-agosto',
}, idempotency_key='saque-2026-08-07-01')

Campo	Tipo	Descrição
`amount`obrigatório	inteiro	Valor a receber, em centavos. Mínimo `500` (R$ 5,00). A taxa é debitada por cima.
`pix_key_type`obrigatório	string	`cpf`, `cnpj`, `phone`, `email` ou `evp` (chave aleatória).
`pix_key`obrigatório	string	A chave. CPF/CNPJ/telefone: só dígitos (aceitamos com pontuação e normalizamos).
`reference`opcional	string	Seu identificador para o saque.

Resposta 201

{
  "object": "withdrawal",
  "id": "wd_1c7fa03e95b846d2f0ba",
  "status": "pending",
  "amount": 100000,
  "fee_amount": 200,
  "total_debited": 100200,
  "currency": "BRL",
  "pix_key": "**********0181",
  "pix_key_type": "cnpj",
  "end_to_end_id": null,
  "processed_at": null,
  "created_at": "2026-08-07T14:32:10-03:00"
}

O valor pedido é o valor recebido. A taxa sai por cima: pedindo 100000 com taxa de 200, chegam R$ 1.000,00 no destino e saem R$ 1.002,00 do seu saldo. É o total_debited que precisa caber no available.

Saldo insuficiente

O saldo é conferido antes de qualquer transferência ser iniciada:

Resposta 422

{
  "error": {
    "code": "insufficient_balance",
    "message": "Saldo insuficiente. Necessário R$ 1.002,00 (valor R$ 1.000,00 + taxa R$ 2,00). Disponível: R$ 458,72.",
    "request_id": "a3f1c09b7e42d85610fb2c7d9a4e5b83"
  }
}

Acompanhar o saque

GET/v1/withdrawals/{id}

GET/v1/withdrawals

Status	Significa
`pending`	Solicitado, aguardando processamento.
`approved`	Aprovado, ainda não transferido.
`processing`	Transferência em andamento.
`paid`	Concluído. O valor chegou na conta de destino.
`rejected`	Recusado. Verifique a chave PIX.
`failed`	Falhou. O valor volta para o seu saldo.
`canceled`	Cancelado. O valor volta para o seu saldo.

Cadastre um webhook para receber withdrawal.paid e withdrawal.failed sem precisar consultar.

Nas consultas, a pix_key vem mascarada — só os 4 últimos caracteres. A chave completa você já tem: foi você quem enviou. Repeti-la em toda listagem só espalharia dado pessoal sem necessidade.

Cuidado com automação de saque

A chave de API pode solicitar saques. Se ela vazar, o dinheiro sai. Antes de automatizar saque:

Use uma chave dedicada, guardada em cofre de segredos, separada da chave que cria cobranças.
Rode a rotina de saque num serviço isolado, sem acesso da internet.
Sempre com Idempotency-Key — sem ela, uma retentativa após timeout faz o saque sair duas vezes.
Monitore withdrawal.paid e reconcilie com o que você solicitou.