Criar Cobrança via Boleto
Gere boletos bancários para cobrança de seus clientes. O boleto pode ser pago em qualquer banco ou lotérica.
POST
/v1/charges/billetCria uma nova cobrança via boleto bancário
Parâmetros da Requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | number | Sim | Valor do boleto em reais (mínimo R$ 5,00) |
customerName | string | Sim | Nome completo do pagador |
customerCpf | string | Sim | CPF ou CNPJ do pagador (apenas números) |
customerEmail | string | Sim | E-mail do pagador |
dueDate | string | Sim | Data de vencimento (formato: YYYY-MM-DD) |
description | string | Não | Descrição do pagamento (aparece no boleto) |
street | string | Sim | Rua do pagador |
number | string | Sim | Número do endereço |
complement | string | Não | Complemento (apto, sala, etc.) |
district | string | Sim | Bairro |
city | string | Sim | Cidade |
state | string | Sim | Estado (sigla de 2 letras, ex: SP) |
zipCode | string | Sim | CEP (8 dígitos, apenas números) |
externalReference | string | Não | Identificador externo para referência (ex: ID do pedido no seu sistema) |
postbackUrl | string | Não | URL de callback para receber notificação quando o pagamento for confirmado |
Resposta de Sucesso
Quando o boleto é criado com sucesso, você receberá:
| Campo | Tipo | Descrição |
|---|---|---|
chargeId | string | ID único da transação para consultas posteriores |
externalId | string | ID da transação no gateway emissor do boleto |
amount | string | Valor bruto do boleto em reais (string com decimal — ex: "150.00") |
netAmount | string | Valor líquido após taxas (string) |
fee | string | Taxa cobrada pela transação (string) |
status | string | Status atual em uppercase (PENDING, RELEASE, CANCELLED, FAILED, etc.) |
billet.barcode | string | Código de barras do boleto (pode vir vazio dependendo do banco emissor) |
billet.digitableLine | string | Linha digitável para pagamento (pode vir vazia dependendo do banco emissor) |
billet.billetUrl | string | URL para download do boleto em PDF (sempre disponível) |
billet.dueDate | string | Data de vencimento do boleto (ISO 8601) |
billet.pixQrCode | string | null | Código PIX copia-e-cola do boleto híbrido (bolix) — quando o banco emissor suporta, o pagador pode quitar o boleto na hora via PIX |
billet.pixQrCodeBase64 | string | null | Imagem do QR Code PIX do bolix (base64), quando disponível |
Sobre os tipos numéricosOs campos
amount, netAmount e fee são retornados como string (serialização de Decimal). Use parseFloat() (JS), float() (Python) ou equivalente antes de fazer cálculos.Fluxo de Pagamento
1. Gere o boleto
Envie a requisição com os dados do cliente e receba o boleto.
2. Exiba para o cliente
Use a billetUrl para redirecionar ou a digitableLine para copiar.
3. Aguarde o pagamento
O webhook será disparado quando o boleto for pago (1-3 dias úteis após pagamento).
CompensaçãoBoletos demoram de 1 a 3 dias úteis para compensar após o pagamento.
Próximo passoConfigure os Webhooks para receber notificações de pagamento.