DiscordStatus
Guias / Guides

Payments via bank slip

Start accepting online bank slip (boleto) payments with Asaas.

Create payments via bank slip (boleto), provide the payment details to the customer, and track the receipt via Webhooks.

📘

Important

By the end of this guide, you will have created a bank slip payment, obtained the digitable line, and prepared your integration to track the payment.

When to use

Use bank slip payments when your integration needs to:

  • provide a payment method with a due date;
  • present the digitable line or the bank slip PDF;
  • apply discounts, interest, or fines;
  • generate installment payments and payment booklets.

Before you start

You need to:

  1. register or look up the customer;
  2. store the ID returned by the API;
  3. define the amount and the due date;
  4. configure the Webhooks related to payments.

See: Register customers to create payments.

How it works

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Register or look up the customer"] --> B["Create the bank slip payment"]
    B --> C["Store the payment ID"]
    C --> D["Provide the bank slip or the digitable line"]
    D --> E["Track the payment via Webhooks"]
    E --> F["Reconcile the receipt"]

    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. Create the payment

Send a request to:

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

The billingType field must be sent as BOLETO.

See the endpoint: Create new payment.

Expected result

The API will return the data of the created payment.

Make sure to store:

  • id: payment identifier;
  • invoiceUrl: invoice address;
  • bankSlipUrl: bank slip PDF address;
  • status: current status of the payment.

The id will be used in subsequent queries and in payment reconciliation.

2. Get the digitable line

To retrieve the digitable line and the barcode, use:

GET /v3/payments/{id}/identificationField

See the endpoint: Get digitable bill line.

Response example:

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

Attention

If the payment amount or due date is updated, retrieve the digitable line again before presenting it to the customer.

3. Configure discount, interest, and fine

These conditions must be provided when creating the payment.

Discount

To apply a 10% discount up to five days before the due date, add:

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

Interest and fine

To apply 1% interest and a 2% fine after the due date, add:

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

See the payment creation reference to check the applicable formats and limits.

After payment, the originalValue and interestValue fields can be used to identify differences between the original amount and the amount received.

4. Track the payment

Configure Webhooks to receive payment status changes.

The main events in this flow are:

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

See:

Do not release products or services based only on the payment's creation. Wait for payment confirmation.

Installment payment and payment booklet

To create an installment plan, provide installmentCount with installmentValue or totalValue.

The response will return the installment ID in the installment field.

To get the payment booklet as a PDF, use:

GET /v3/installments/{id}/paymentBook

The {id} parameter represents the installment ID.

See:

Pix QR Code on the bank slip

To display a Pix QR Code on the bank slip PDF, keep a Pix key registered in the Asaas account.

See Payments via Pix.

Common errors

If the payment is not created, check whether:

  • the customer belongs to the same account;
  • billingType was sent as BOLETO;
  • the amount and due date are valid;
  • the URL and the API key belong to the same environment;
  • the discount, interest, or fine fields are correct.

In case of a timeout or inconclusive response, look up existing payments before repeating the creation to avoid duplicates.

Next steps

Updated 7 days ago

Did this page help you?