DiscordStatus
Guias / Guides

Cobranças via boleto

Comece a aceitar pagamentos de boletos online com o Asaas.

Crie cobranças via boleto, disponibilize os dados de pagamento ao cliente e acompanhe o recebimento por Webhooks.

📘

Importante

Ao concluir este guia, você terá criado uma cobrança via boleto, obtido a linha digitável e preparado sua integração para acompanhar o pagamento.

Quando utilizar

Utilize cobranças via boleto quando sua integração precisar:

  • disponibilizar uma forma de pagamento com vencimento;
  • apresentar a linha digitável ou o boleto em PDF;
  • aplicar descontos, juros ou multas;
  • gerar cobranças parceladas e carnês.

Antes de começar

Você precisa:

  1. cadastrar ou localizar o cliente;
  2. armazenar o ID retornado pela API;
  3. definir o valor e a data de vencimento;
  4. configurar os Webhooks relacionados às cobranças.

Consulte: Cadastre clientes para criar cobranças.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Cadastrar ou localizar o cliente"] --> B["Criar a cobrança via boleto"]
    B --> C["Armazenar o ID da cobrança"]
    C --> D["Disponibilizar o boleto ou a linha digitável"]
    D --> E["Acompanhar o pagamento por Webhooks"]
    E --> F["Conciliar o recebimento"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Crie a cobrança

Envie uma requisição para:

POST /v3/payments
{
  "customer": "cus_000005219613",
  "billingType": "BOLETO",
  "value": 100.00,
  "dueDate": "2027-01-15",
  "externalReference": "PEDIDO-123"
}

O campo billingType deve ser enviado como BOLETO.

Consulte o endpoint: Criar nova cobrança.

Resultado esperado

A API retornará os dados da cobrança criada.

Armazene principalmente:

  • id: identificador da cobrança;
  • invoiceUrl: endereço da fatura;
  • bankSlipUrl: endereço do boleto em PDF;
  • status: situação atual da cobrança.

O id será utilizado nas próximas consultas e na conciliação do pagamento.

2. Obtenha a linha digitável

Para recuperar a linha digitável e o código de barras, utilize:

GET /v3/payments/{id}/identificationField

Consulte o endpoint: Obter linha digitável do boleto.

Exemplo de resposta:

{
  "identificationField": "00190000090275928800021932978170187890000005000",
  "nossoNumero": "6543",
  "barCode": "00191878900000050000000002759288002193297817"
}
⚠️

Atenção

Se o valor ou o vencimento da cobrança for atualizado, recupere novamente a linha digitável antes de apresentá-la ao cliente.

3. Configure desconto, juros e multa

Essas condições devem ser informadas durante a criação da cobrança.

Desconto

Para aplicar um desconto de 10% até cinco dias antes do vencimento, adicione:

{
  "discount": {
    "value": 10,
    "dueDateLimitDays": 5,
    "type": "PERCENTAGE"
  }
}

Juros e multa

Para aplicar juros de 1% e multa de 2% após o vencimento, adicione:

{
  "interest": {
    "value": 1
  },
  "fine": {
    "value": 2
  }
}

Consulte a referência de criação de cobranças para verificar os formatos e limites aplicáveis.

Após o pagamento, os campos originalValue e interestValue podem ser utilizados para identificar diferenças entre o valor original e o valor recebido.

4. Acompanhe o pagamento

Configure Webhooks para receber as alterações de status da cobrança.

Os principais eventos desse fluxo são:

  • PAYMENT_CONFIRMED;
  • PAYMENT_RECEIVED;
  • PAYMENT_OVERDUE;
  • PAYMENT_REFUNDED.

Consulte:

Não libere produtos ou serviços considerando apenas a criação da cobrança. Aguarde a confirmação do pagamento.

Cobrança parcelada e carnê

Para criar um parcelamento, informe installmentCount com installmentValue ou totalValue.

A resposta retornará o ID do parcelamento no campo installment.

Para obter o carnê em PDF, utilize:

GET /v3/installments/{id}/paymentBook

O parâmetro {id} representa o ID do parcelamento.

Consulte:

QR Code Pix no boleto

Para exibir um QR Code Pix no PDF do boleto, mantenha uma chave Pix cadastrada na conta Asaas.

Consulte Cobranças via Pix.

Erros comuns

Caso a cobrança não seja criada, verifique se:

  • o cliente pertence à mesma conta;
  • billingType foi enviado como BOLETO;
  • o valor e o vencimento são válidos;
  • a URL e a chave de API pertencem ao mesmo ambiente;
  • os campos de desconto, juros ou multa estão corretos.

Em caso de timeout ou resposta inconclusiva, consulte as cobranças existentes antes de repetir a criação para evitar duplicidades.

Próximos passos

Updated 1 day ago

What’s Next

Did this page help you?