Important rules

Before creating a payment, validate the rules below. They determine which fields to send and when the boleto can be processed.

Boleto identification

The identificationField field is required and must contain the boleto's digitable line.

From it, Asaas identifies and validates the information available in the boleto, such as issuer, bill type, due date, and amount.

When the boleto itself does not provide some required information, use the additional fields provided in the endpoint.

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

Interest, fine, and discount

Only send interest, fine, and discount when they apply to the payment.

Cutoff times for same-day clearing

On business days, same-day clearing depends on the type and amount of the boleto:

Outside the applicable window, do not assume the payment will be cleared on the same day.

To correctly define when to send scheduleDate, see Immediate payment x Scheduled payment.

Overdue boletos

Payment after the due date depends on whether the issuer allows clearing after the due date.

When the overdue boleto is accepted:

• do not send scheduleDate;
• request the payment on the same day;
• respect the operational time applicable to the boleto.

If scheduleDate is sent for an overdue boleto, the request may be rejected with the message Contas vencidas não podem ser agendadas.

Track processing

Acceptance of the request does not confirm that the payment has been completed.

Use the Bill Payment Events to automatically track state changes. Prefer Webhooks over periodic API queries.

When a failure occurs, handle the returned reason before making a new attempt.

Next steps

• Immediate payment x Scheduled payment
• Possible statuses
• Common errors and exceptions — Bill Payment
• Bill Payment Events
• Testing in Sandbox