Introduction - Bill Payment

Bill Payment lets you create boleto payments through the Asaas API using the boleto's digitable line.

On this page, you will understand the general flow of the operation, the difference between paying on the same day and scheduling a future date, and how to track processing.

Before you start

To use Bill Payment:

• the account must have completed proof of life;
• obtain the boleto's digitable line;
• consider the type, amount, due date, and desired payment date;
• configure Webhooks to track the operation's state changes.

Time and processing rules vary depending on the boleto. See Immediate payment x Scheduled payment and Important rules before implementing these validations.

How it works

Creating the payment uses the POST /v3/bill endpoint. The identificationField field provides the digitable line, from which Asaas identifies and validates the available boleto data.

When you want to schedule the payment for a future date, use scheduleDate.

See the full reference for the Create a bill payment endpoint.

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Get the digitable line"] --> B["Define when to pay"]
    B --> C["Create the payment"]
    C --> D["Validate the boleto"]
    D --> E["Process the operation"]
    E --> F["Receive Webhooks"]
    F --> G["Update the payment"]

    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,F validacao
    class G sucesso

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

Same-day or scheduled payment

Choose the flow according to the operation's needs.

Do not hard-code a single time rule for all boletos. Utility bills, collection boletos, and higher-value operations have different limits.

See Immediate payment x Scheduled payment to implement both scenarios and Important rules to handle boleto-specific conditions.

Track processing via Webhooks

Creating the operation does not confirm that the boleto has been paid. The payment may go through intermediate states before being completed, failing, being canceled, or being refunded.

Use the Bill Payment Events to automatically receive state changes.

Prefer Webhooks over periodic API queries. Use a GET query when you need to retrieve the current state of an operation on demand.

See Possible statuses to define how your application should interpret each state.

Sandbox

In Sandbox, use boletos created in the Sandbox account itself. The environment simulates the Bill Payment flow, but it does not perform bank clearing or move real money.

Use this environment to validate the payload, error handling, and Webhook receipt.

See Testing in Sandbox.

Next steps

• Immediate payment x Scheduled payment
• Important rules
• Possible statuses
• Bill Payment Events
• Testing in Sandbox