Receber pagamentos

Boleto

Cobrança com linha digitável e código de barras.

Cobrança por boleto bancário. Mesma chamada do PIX, trocando o payment_method. A resposta traz a linha digitável e o código de barras.

A API devolve apenas os códigos — não um PDF. Você recebe a linha digitável e o código de barras e monta o documento no seu layout, com a sua marca. Assim o boleto que o seu cliente recebe é o seu, e a aparência dele não depende de um template nosso.

POST/v1/charges

Criar a cobrança

Requisição

curl -X POST https://novexfinance.com.br/api/v1/charges \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fatura-2026-08-1174" \
  -d '{
    "payment_method": "boleto",
    "amount": 45000,
    "description": "Fatura de agosto/2026",
    "reference": "1174",
    "customer": {
      "name": "Construtora Exemplo LTDA",
      "email": "financeiro@exemplo.com.br",
      "phone": "1133224455",
      "document": "11222333000181"
    }
  }'

$charge = $novex->post('/charges', [
    'payment_method' => 'boleto',
    'amount'         => 45000,
    'description'    => 'Fatura de agosto/2026',
    'reference'      => '1174',
    'customer'       => [
        'name'     => 'Construtora Exemplo LTDA',
        'email'    => 'financeiro@exemplo.com.br',
        'phone'    => '1133224455',
        'document' => '11222333000181',
    ],
], 'fatura-2026-08-1174');

$linhaDigitavel = $charge['boleto']['digitable_line'];
$codigoBarras   = $charge['boleto']['barcode'];

const charge = await novex.post('/charges', {
  payment_method: 'boleto',
  amount: 45000,
  description: 'Fatura de agosto/2026',
  reference: '1174',
  customer: {
    name: 'Construtora Exemplo LTDA',
    email: 'financeiro@exemplo.com.br',
    phone: '1133224455',
    document: '11222333000181',
  },
}, { idempotencyKey: 'fatura-2026-08-1174' });

const { digitable_line, barcode } = charge.boleto;

charge = novex.post('/charges', {
    'payment_method': 'boleto',
    'amount': 45000,
    'description': 'Fatura de agosto/2026',
    'reference': '1174',
    'customer': {
        'name': 'Construtora Exemplo LTDA',
        'email': 'financeiro@exemplo.com.br',
        'phone': '1133224455',
        'document': '11222333000181',
    },
}, idempotency_key='fatura-2026-08-1174')

linha = charge['boleto']['digitable_line']

Os campos de entrada são os mesmos do PIX — só muda o payment_method. CNPJ é aceito normalmente em customer.document.

Resposta

Resposta 201

{
  "object": "charge",
  "id": "ch_5e08b3d71fa9426c8b03",
  "status": "pending",
  "amount": 45000,
  "currency": "BRL",
  "payment_method": "boleto",
  "description": "Fatura de agosto/2026",
  "reference": "1174",
  "customer": {
    "name": "Construtora Exemplo LTDA",
    "email": "financeiro@exemplo.com.br",
    "phone": "1133224455",
    "document": "11222333000181",
    "document_type": "cnpj"
  },
  "paid_at": null,
  "created_at": "2026-08-07T14:32:10-03:00",
  "boleto": {
    "digitable_line": "34191.79001 01043.510047 91020.150008 097704500045000",
    "barcode": "34199977000045000000010435100479102015000",
    "expires_at": "2026-08-14T23:59:59-03:00"
  }
}

Campo da resposta	Tipo	Descrição
`boleto.digitable_line`opcional	string	Linha digitável formatada (47 dígitos). É o que o cliente digita no internet banking.
`boleto.barcode`opcional	string	Código de barras (44 dígitos), sem formatação. Use para gerar a imagem do código.
`boleto.expires_at`opcional	data	Data de vencimento.

Montar o documento

Com a linha digitável e o código de barras você tem tudo. Padrão do mercado para o código de barras de boleto: Interleaved 2 of 5, com 44 dígitos.

Gerar o código de barras

// picqer/php-barcode-generator, por exemplo
$generator = new BarcodeGeneratorPNG();
$png = $generator->getBarcode(
    $charge['boleto']['barcode'],
    $generator::TYPE_INTERLEAVED_2_5,
    2,
    70
);

echo '<img src="data:image/png;base64,' . base64_encode($png) . '">';
echo '<p>' . $charge['boleto']['digitable_line'] . '</p>';

import bwipjs from 'bwip-js';

const png = await bwipjs.toBuffer({
  bcid: 'interleaved2of5',
  text: charge.boleto.barcode,
  height: 12,
  includetext: false,
});

Envie sempre a linha digitável em texto, junto com a imagem. Boa parte dos pagamentos de boleto acontece pelo aplicativo do banco, onde copiar e colar é mais rápido — e é o único caminho quando a imagem não carrega no e-mail.

Ciclo de vida

Status	Significa
`pending`	Boleto emitido, aguardando pagamento.
`paid`	Pagamento compensado. Chega por webhook `charge.paid`.
`refunded`	Valor devolvido ao pagador.
`failed`	A cobrança não pôde ser concluída.

Boleto não confirma na hora. O pagamento é compensado pelo banco e só então o status vira paid — normalmente em 1 dia útil. Não libere pedido contra boleto emitido; espere o evento charge.paid.

Liquidação

O valor entra no saldo disponível assim que o pagamento é confirmado. A compensação bancária já aconteceu antes de o status virar paid, então não há prazo adicional depois disso.