Bill Payment events

Listen to Asaas events to keep your integration up to date.

Use Bill Payment events to automatically track the processing of payments made through Asaas.

Each notification indicates the event that occurred in event and the current payment data in the bill object. To track state changes, prefer Webhooks instead of periodic API queries.

Available events

Event	When it occurs
`BILL_CREATED`	A new bill payment is created.
`BILL_PENDING`	The payment is awaiting processing.
`BILL_BANK_PROCESSING`	The payment is in bank processing.
`BILL_PAID`	The payment is completed.
`BILL_CANCELLED`	The payment is cancelled.
`BILL_FAILED`	The payment fails.
`BILL_REFUNDED`	The payment is refunded.

How to interpret the events

Event	Handling in the integration
`BILL_CREATED`	Record the operation and associate `bill.id` with the payment in your system.
`BILL_PENDING`	Keep the payment as pending.
`BILL_BANK_PROCESSING`	Indicate that the payment is in bank processing.
`BILL_PAID`	Confirm the payment and use `transactionReceiptUrl` when the receipt is available.
`BILL_CANCELLED`	Update the operation as cancelled.
`BILL_FAILED`	Mark the operation as failed and check `failReasons`.
`BILL_REFUNDED`	Update the operation to reflect the refund.

event identifies the change notified by the Webhook. bill.status represents the current state of the payment in the payload.

Payment flows

Payment completed

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["BILL_CREATED"] --> B["BILL_PENDING"]
    B --> C["BILL_BANK_PROCESSING"]
    C --> D["BILL_PAID"]

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

    class A inicio
    class B,C validacao
    class D sucesso

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

Processing failure

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["BILL_CREATED"] --> B["BILL_PENDING"]
    B --> C["BILL_FAILED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:17px

    class A inicio
    class B validacao
    class C respostaNao

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

When you receive BILL_FAILED, use bill.failReasons to identify the cause before recommending a new attempt.

Payment cancelled

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["BILL_CREATED"] --> B["BILL_CANCELLED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B sucesso

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

The events represent changes in processing. Do not assume that every operation will necessarily go through all intermediate states before the final result.

Event payload

The notification is sent via POST with the event and the bill payment data.

{
    "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 phone 01/12",
        "companyName": null,
        "transactionReceiptUrl": "https://www.asaas.com/comprovantes/00016578",
        "canBeCancelled": false,
        "failReasons": null
    }
}

Important payload fields

Field	Description
`id`	Unique identifier of the event. Use it for idempotence.
`event`	Identifies the event received.
`bill.id`	Bill payment identifier.
`bill.status`	Current state of the payment.
`bill.paymentDate`	Effective payment date.
`bill.transactionReceiptUrl`	Receipt URL, when available.
`bill.failReasons`	Reasons for the failure, when there are any.
`bill.canBeCancelled`	Indicates whether the payment can still be cancelled.

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

How to handle the events

When receiving an event:

identify the change through the event field;
persist the id to prevent duplicate processing;
use bill.id to find the payment in your system;
update the operation according to event and bill.status;
respond HTTP 200 after confirming persistence;
process additional rules asynchronously.

Webhooks follow the at least once model, so the same event may be sent more than once.

See how to implement idempotence in Webhooks.

🚧
Attention

As new products and features are added to Asaas, new attributes may be included in the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes that your application does not handle, as this may interrupt the sync queue.

We will send an email and announce on our Discord when new fields are added to the Webhook. The email will be sent to the notification email address defined in the Webhook settings.

Next steps

Updated 20 days ago

Did this page help you?