Events for Bill Payments

You can use Webhooks so that your system is notified about changes that occur in bill payments.

The events notified by Asaas are:

• BILL_CREATED - New bill payment created.
• BILL_PENDING - Bill payment awaiting processing.
• BILL_BANK_PROCESSING - Bill payment under bank processing.
• BILL_PAID - Bill payment completed.
• BILL_CANCELLED - Bill payment canceled.
• BILL_FAILED - Bill payment failed.
• BILL_REFUNDED - Bill payment refunded.

When to use

Bill payment Webhooks are recommended when your application needs to automatically track the progress of bills paid through Asaas.

Some examples:

• financial reconciliation;
• ERP updates;
• payment monitoring;
• financial auditing;
• automatic receipt generation;
• synchronization with external systems.

Important behaviors

Asaas Webhooks use the at least once delivery model. This means that the same event may be sent more than once.

For this reason, it is recommended to implement idempotency using the field:

id

from the received event.

In addition:

• HTTP responses outside the 2xx range may trigger new delivery attempts;
• the queue may be interrupted after consecutive failures;
• events remain stored for up to 14 days;
• new attributes may be added to the payload in the future.

Common event flow

Typically, the flow occurs as follows:

BILL_CREATED
↓
BILL_PENDING
↓
BILL_BANK_PROCESSING
↓
BILL_PAID

In specific situations, the following may occur:

BILL_CREATED
↓
BILL_PENDING
↓
BILL_FAILED

or

BILL_CREATED
↓
BILL_CANCELLED

Important fields

Example JSON received [POST]

The notification consists of a POST containing a JSON, as shown below:

{
    "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
    "event": "BILL_PAID",
    "dateCreated": "2024-06-12 16:45:03",
    "account": {
        "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
        "ownerId": null
    },
    "bill": {
        "object": "bill",
        "id": "f1bce822-6f37-4905-8de8-f1af9f2f4bab",
        "status": "PAID",
        "value": 29.90,
        "discount": 0.00,
        "interest": 0.00,
        "fine": 0.00,
        "identificationField": "03399.77779 29900.000000 04751.101017 1 81510000002990",
        "dueDate": "2020-01-31",
        "scheduleDate": "2020-01-31",
        "paymentDate": "2020-01-31",
        "fee": 0.00,
        "description": "Mobile bill 12/01",
        "companyName": null,
        "transactionReceiptUrl": "https://www.asaas.com/comprovantes/00016578",
        "canBeCancelled": false,
        "failReasons": null
    }
}

👍

Webhook response with typing and ENUMs

If you want to know the type of each field and the available ENUM values, check the 200 response of the endpoint "Retrieve a single bill payment" in the documentation.

Security and best practices

We recommend:

• validating the asaas-access-token header;
• responding quickly with HTTP 2xx;
• implementing idempotency using the event identifier;
• processing events asynchronously;
• monitoring Webhook Logs;
• preparing the application for new attributes that may be added in the future.

Common errors

Duplicate event

Since delivery follows the at least once model, the same event may be received more than once.

Use the event id field to avoid duplicate processing.

HTTP response outside the 2xx range

Responses outside the 2xx family may trigger new delivery attempts.

New attributes in the payload

Your application should ignore unknown fields to avoid future failures.

Operational impacts

If your application is not properly prepared to receive Webhooks, the following may occur:

• new delivery attempts;
• synchronization queue interruption;
• delays in financial reconciliation;
• inconsistencies between systems;
• permanent event loss after 14 days.

🚧

Attention

• As new products and features are introduced in Asaas, new attributes may be added to the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes not handled by your application, as this may cause interruption of the synchronization queue.
• We will send an email and notify our Discord whenever new fields are added to the Webhook. Notifications will be sent to the notification email configured in the Webhook settings.