Eventos para pague contas

Use os eventos de Pague Contas para acompanhar automaticamente o processamento de pagamentos realizados pelo Asaas.

Cada notificação informa o evento ocorrido em event e os dados atuais do pagamento no objeto bill. Para acompanhar mudanças de estado, prefira Webhooks em vez de consultas periódicas à API.

Eventos disponíveis

Como interpretar os eventos

event identifica a alteração notificada pelo Webhook. bill.status representa o estado atual do pagamento no payload.

Fluxos do pagamento

Pagamento concluído

%%{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

Falha no processamento

%%{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

Ao receber BILL_FAILED, utilize bill.failReasons para identificar a causa antes de orientar uma nova tentativa.

Pagamento cancelado

%%{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

Os eventos representam alterações no processamento. Não assuma que toda operação passará obrigatoriamente por todos os estados intermediários antes do resultado final.

Payload do evento

A notificação é enviada via POST com o evento e os dados do pagamento de contas.

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

Campos importantes do payload

Como tratar os eventos

Ao receber um evento:

1. identifique a alteração pelo campo event;
2. persista o id para impedir processamento duplicado;
3. utilize bill.id para localizar o pagamento no seu sistema;
4. atualize a operação conforme event e bill.status;
5. responda HTTP 200 após confirmar a persistência;
6. processe regras adicionais de forma assíncrona.

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez.

Consulte como implementar idempotência em Webhooks.

Próximos passos

• Conheça o fluxo do Pague Contas
• Consulte os status do pagamento
• Receba eventos do Asaas no seu endpoint de Webhook
• Implemente idempotência em Webhooks
• Monitore os Logs de Webhooks