Criando um Boleto
Emita um boleto com vencimento, encargos e registro assíncrono.
As datas dos exemplos são demonstrativas. Antes de executar, atualize o vencimento ou payday para uma data atual ou futura em UTC e confira a data limite de desconto, quando houver.
POST
/v1/charges
X-API-KEY
201 Created
Pré-requisitos
Conta habilitada, chave do ambiente, cadastro e endereço do lojista completos, dados válidos do pagador e endpoint de webhook preparado. Consulte Credenciais de acesso e Ambientes e requisições.
Requisição mínima
Substitua o vencimento por uma data atual ou futura antes de executar.
{
"amount": 100.5,
"description": "Pedido de teste 1003",
"due_date": "2026-10-16",
"grace_period": 7,
"payer": {
"name": "Pagador de teste",
"document": "52998224725",
"zip": "01310100",
"street": "Avenida de teste",
"city": "São Paulo",
"state": "SP",
"number": "100",
"neighborhood": "Centro"
}
}Campos
due_date
string
Sim
Data atual ou futura em YYYY-MM-DD.
grace_period
integer
Sim
Tolerância após vencimento, de 1 a 30 dias.
amount
number
Sim
Pelo menos R$ 5,00, até duas casas e compatível com tarifas/encargos.
description
string
Sim
Texto não vazio.
payer.name
string
Sim
Nome não vazio.
payer.document
string
Sim
CPF/CNPJ válido.
payer.zip
string
Sim
CEP com oito dígitos.
payer.street, city, state, number, neighborhood
string
Sim
Endereço do pagador; mantenha todos os campos como strings.
fine
number
Não
Percentual da multa; 0 desabilita, ou de 0.1 a 100, sujeito aos limites da cobrança.
interest
number
Não
Percentual mensal de juros após vencimento; cálculo diário proporcional usando divisor 30. 0 desabilita; de 0.1 a 100, sujeito aos limites da cobrança.
discount
object
Não
Tipo fixed ou percentage, valor e data limite.
notification_url
string
Não
URL de webhook; use HTTPS público.
metadata
array
Não
Objetos key/value como strings não vazias.
customer_code
string
Não
Referência comercial; não garante idempotência.
Campos opcionais devem ser omitidos quando não utilizados. Não envie null. O desconto exige type, amount e limit_date; a data limite não pode ser posterior ao vencimento. Confira o valor final da cobrança após desconto.
Multa, juros e desconto
fine é o percentual de multa. interest é o percentual mensal de juros: o valor diário é valor original × (interest / 100) / 30. Os juros acumulam pelos dias de atraso; não interprete interest: 1 como 1% ao dia.
Exemplo: boleto de R$ 150,00 com interest: 1 gera R$ 0,05 de juros por dia de atraso, antes dos demais encargos ou descontos. A multa tem papel distinto dos juros; fine: 2 representa 2% de multa sobre o valor original.
O registro e o valor efetivamente pago devem ser reconciliados com os dados retornados pela API. A regra de cálculo proporcional está descrita na documentação de emissão do provedor.
Requisição com opções
Executar com cURL
Antes de executar, configure PAGOU_BASE_URL e PAGOU_API_KEY conforme Ambientes e requisições. Os exemplos usam dados fictícios e não contêm credenciais válidas.
Atualize as datas antes de executar.
Resposta e registro
O retorno 201 Created contém um objeto com id e os dados de criação. fine e interest podem retornar 0 quando omitidos. A resposta inicial não contém necessariamente linha digitável, código de barras ou dados de registro.
Guarde o id do corpo. O header Location pode usar /charge/{id}; para consulta, utilize GET /v1/charges/{id}.
Aguarde charge.created nos Webhooks de boleto ou consulte até os dados de registro estarem disponíveis. Depois, apresente a linha digitável/código de barras ou os links:
HTML:
https://fatura.pagou.com.br/boleto/{id}PDF:
https://fatura.pagou.com.br/boleto/pdf/{id}
Essas visualizações podem não estar disponíveis antes do registro; confira o ambiente da cobrança. O evento charge.paid é a confirmação de pagamento, distinta do registro.
Erros e repetição
400: confira campos, datas, endereço, documento e valor final. 401: confira credencial e ambiente. Não configure repetição automática de operações financeiras. Timeout, conexão interrompida ou erro do servidor podem deixar o resultado indeterminado. Consulte os registros disponíveis antes de reenviar. Veja Erros e recuperação.
Guias relacionados
Primeiros passos · Erros e recuperação · Idempotência e repetição · Recebendo webhooks
Last updated