Criar boleto
POST
/api/charges
Autenticação
Bearer pela sua API Key real. Sem o header → 401. Chave sem escopo → 403 insufficient_scope.Criar boleto
charges:write · Pré-requisito: KYC aprovado. Rate limit: 100 req/min.POST /api/charges), mudando paymentMethod para "boleto". Boleto é assíncrono: nasce pending e a baixa chega via webhook EVENT:CHARGE_PAID (tipicamente D+1 a D+2 após o pagamento).Pré-requisito de conta (opt-in)
403. Contas de teste → 400.Body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
paymentMethod | string | sim | "boleto". Sem isso (ou "pix"/omisso) cria PIX. |
value | number | sim | Valor em REAIS (ex: 129.90). > 0, máx 1.000.000. |
description | string | não | Máx 255 chars. |
dueInDays | int | não | Dias até o vencimento (1–60). Default: 3. |
webhook_url | string | não | URL HTTPS do webhook desta cobrança. |
customer.name | string | sim | Nome do pagador. |
customer.email | string | sim | Email válido. |
customer.taxID | string | sim | CPF (11) ou CNPJ (14), só números. |
customer.phone | string | não | Ex: +5511999998888. |
customer.address.street | string | sim | Logradouro. |
customer.address.number | string | sim | Número. |
customer.address.zipCode | string | sim | CEP (8 dígitos). |
customer.address.city | string | sim | Cidade. |
customer.address.state | string | sim | UF (2 letras). |
customer.address.neighborhood | string | não | Bairro. |
Boleto registrado exige nome + CPF/CNPJ + endereço do pagador.
Resposta
200 OK → { success, data: { id, correlationID, paymentMethod: "BOLETO", status: "pending", boletoLine, dueAt, value } }.boletoLine — linha digitável (o que o cliente copia). É o único artefato entregue; não expomos URLs externas do emissor (PDF/código de barras).value em centavos. Consulte o status por GET /api/charges/{correlationID}.Requisição
Parâmetros Header
Parâmetros Bodyapplication/json
Respostas
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/charges' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"paymentMethod": "boleto",
"value": 129.9,
"description": "Pedido #1234",
"dueInDays": 3,
"customer": {
"name": "Maria Souza",
"email": "maria@exemplo.com",
"phone": "+5511999998888",
"taxID": "39053344705",
"address": {
"street": "Av. Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"zipCode": "01310100",
"city": "São Paulo",
"state": "SP"
}
},
"webhook_url": "https://seu-dominio.com/webhooks/dotfy"
}'Response Response Example
200 - Sucesso (200) — boleto gerado
{
"success": true,
"data": {
"id": "clch_boleto_0001",
"correlationID": "boleto_api_1714000000000_a1b2c3d4e5",
"correlationId": "boleto_api_1714000000000_a1b2c3d4e5",
"paymentMethod": "BOLETO",
"status": "pending",
"boletoLine": "23793.38128 60007.827136 95000.063305 8 84410000012990",
"dueAt": "2026-07-17T12:00:00.000Z",
"value": 12990
}
}Modificado em 2026-07-14 04:02:21