Eventos para cobranças

Escute os eventos do Asaas para ter sua integração em dia.

Eventos para cobranças

Use os eventos de cobrança para acompanhar mudanças relacionadas a pagamentos, recebimentos, estornos, chargebacks, negativação e Split.

Cada notificação é enviada por Webhook com o tipo do evento em event e os dados da cobrança no objeto payment.

Eventos disponíveis

Ciclo da cobrança e pagamento

Evento	Quando ocorre
`PAYMENT_CREATED`	Geração de nova cobrança.
`PAYMENT_AWAITING_RISK_ANALYSIS`	Pagamento em cartão aguardando aprovação pela análise manual de risco.
`PAYMENT_APPROVED_BY_RISK_ANALYSIS`	Pagamento em cartão aprovado pela análise manual de risco.
`PAYMENT_REPROVED_BY_RISK_ANALYSIS`	Pagamento em cartão reprovado pela análise manual de risco.
`PAYMENT_AUTHORIZED`	Pagamento em cartão autorizado e que precisa ser capturado.
`PAYMENT_UPDATED`	Alteração no vencimento ou valor de cobrança existente.
`PAYMENT_CONFIRMED`	Pagamento efetuado, mas com saldo ainda não disponibilizado.
`PAYMENT_RECEIVED`	Cobrança recebida, com valor disponível na conta Asaas.
`PAYMENT_CREDIT_CARD_CAPTURE_REFUSED`	Falha na captura do pagamento com cartão de crédito.
`PAYMENT_ANTICIPATED`	Cobrança antecipada.
`PAYMENT_OVERDUE`	Cobrança vencida.
`PAYMENT_DELETED`	Cobrança removida.
`PAYMENT_RESTORED`	Cobrança restaurada.

Estornos e chargebacks

Evento	Quando ocorre
`PAYMENT_REFUNDED`	Cobrança estornada.
`PAYMENT_PARTIALLY_REFUNDED`	Cobrança estornada parcialmente.
`PAYMENT_REFUND_IN_PROGRESS`	Estorno em processamento. A liquidação já está agendada e a cobrança será estornada após sua execução.
`PAYMENT_REFUND_DENIED`	Estorno negado. Disponível somente para boletos.
`PAYMENT_RECEIVED_IN_CASH_UNDONE`	Recebimento em dinheiro desfeito.
`PAYMENT_CHARGEBACK_REQUESTED`	Chargeback recebido.
`PAYMENT_CHARGEBACK_DISPUTE`	Chargeback em disputa após apresentação de documentos para contestação.
`PAYMENT_AWAITING_CHARGEBACK_REVERSAL`	Disputa vencida, aguardando repasse da adquirente.

Boleto, negativação e visualização

Evento	Quando ocorre
`PAYMENT_DUNNING_REQUESTED`	Requisição de negativação.
`PAYMENT_DUNNING_RECEIVED`	Recebimento de negativação.
`PAYMENT_BANK_SLIP_CANCELLED`	Registro do boleto cancelado por expiração do prazo de pagamento após o vencimento. Não indica a remoção da cobrança.
`PAYMENT_BANK_SLIP_VIEWED`	Boleto da cobrança visualizado pelo cliente.
`PAYMENT_CHECKOUT_VIEWED`	Fatura da cobrança visualizada pelo cliente.

Split

Evento	Quando ocorre
`PAYMENT_SPLIT_CANCELLED`	Um Split da cobrança foi cancelado.
`PAYMENT_SPLIT_DIVERGENCE_BLOCK`	Valor da cobrança bloqueado por divergência de Split.
`PAYMENT_SPLIT_DIVERGENCE_BLOCK_FINISHED`	Bloqueio por divergência de Split finalizado.
`PAYMENT_SPLIT_DONE`	Um Split da cobrança foi liquidado.

Payload do evento

Cada evento de cobrança é enviado via POST com os dados da cobrança.

Exemplo:

{
   "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
   "event":"PAYMENT_RECEIVED",
   "dateCreated": "2024-06-12 16:45:03",
   "account": {
      "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
      "ownerId": null
   },
   "payment":{
      "object":"payment",
      "id":"pay_080225913252",
      "dateCreated":"2021-01-01",
      "customer":"cus_G7Dvo4iphUNk",
      "subscription":"sub_VXJBYgP2u0eO",
      "installment":"2765d086-c7c5-5cca-898a-4262d212587c",
      "paymentLink":"123517639363",
      "dueDate":"2021-01-01",
      "originalDueDate":"2021-01-01",
      "value":100,
      "netValue":94.51,
      "originalValue":null,
      "interestValue":null,
      "nossoNumero": null,
      "description":"Pedido 056984",
      "externalReference":"056984",
      "billingType":"CREDIT_CARD",
      "status":"RECEIVED",
      "pixTransaction":null,
      "confirmedDate":"2021-01-01",
      "paymentDate":"2021-01-01",
      "clientPaymentDate":"2021-01-01",
      "installmentNumber": null,
      "creditDate":"2021-02-01",
      "custody": null,
      "estimatedCreditDate":"2021-02-01",
      "invoiceUrl":"https://www.asaas.com/i/080225913252",
      "bankSlipUrl":null,
      "transactionReceiptUrl":"https://www.asaas.com/comprovantes/4937311816045162",
      "invoiceNumber":"00005101",
      "deleted":false,
      "anticipated":false,
      "anticipable":false,
      "lastInvoiceViewedDate":"2021-01-01 12:54:56",
      "lastBankSlipViewedDate":null,
      "postalService":false,
      "creditCard":{
         "creditCardNumber":"8829",
         "creditCardBrand":"MASTERCARD",
         "creditCardToken":"a75a1d98-c52d-4a6b-a413-71e00b193c99"
      },
      "discount":{
         "value":0.00,
         "dueDateLimitDays":0,
         "limitedDate": null,
         "type":"FIXED"
      },
      "fine":{
         "value":0.00,
         "type":"FIXED"
      },
      "interest":{
         "value":0.00,
         "type":"PERCENTAGE"
      },
      "split":[
         {
            "id": "c788f2e1-0a5b-41b9-b0be-ff3641fb0cbe",
            "walletId":"48548710-9baa-4ec1-a11f-9010193527c6",
            "fixedValue":20,
            "status":"PENDING",
            "refusalReason": null,
            "externalReference": null,
            "description": null
         },
         {
            "id": "e754f2e1-09mn-88pj-l552-df38j1fbll1c",
            "walletId":"0b763922-aa88-4cbe-a567-e3fe8511fa06",
            "percentualValue":10,
            "status":"PENDING",
            "refusalReason": null,
            "externalReference": null,
            "description": null
         }
      ],
      "chargeback": {
          "status": "REQUESTED",
          "reason": "PROCESS_ERROR"
      },
      "refunds": null
   }
}

📘
Campos opcionais

subscription: retornado apenas quando a cobrança pertence a uma assinatura.

installment: retornado apenas quando a cobrança pertence a um parcelamento.

paymentLink: identificador do link de pagamento que originou a cobrança.

originalValue: retornado quando o valor efetivamente pago é diferente do valor original da cobrança.

O array split é retornado somente para cobranças com Split de Pagamento configurado.

👍
Retorno do Webhook com tipagem e ENUMs
Caso você queira saber qual o tipo de cada campo e os retornos de ENUMs disponíveis, confira a resposta 200 no endpoint "Recuperar uma única cobrança" na documentação.

Quando um valor entra na conta Asaas, a receita é associada a uma cobrança. Isso também ocorre em recebimentos criados automaticamente a partir de Pix ou TED.

Consulte como o Asaas trata receitas na conta.

🚧
Atenção

Com a entrada de novos produtos e funções dentro do Asaas, é possível que novos atributos sejam incluídos no Webhook. É muito importante que seu código esteja preparado para não gerar exceções caso o Asaas devolva novos atributos não tratados pela sua aplicação, pois isso poderá causar interrupção na fila de sincronização.

Enviaremos um e-mail e avisaremos em nosso Discord quando novos campos forem incluídos no Webhook. O disparo será feito para o e-mail de notificação definido nas configurações do webhook.

O array de split será devolvido apenas quando a cobrança possuir configurações de Split de Pagamento.

Fluxos de recebimento

Os eventos recebidos variam conforme o meio de pagamento e o vencimento da cobrança.

Boleto

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B{"Cobrança está em dia?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["PAYMENT_CONFIRMED"]
    BNao --> D["PAYMENT_OVERDUE"]
    D --> C
    C --> E["PAYMENT_RECEIVED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B decisao
    class C,D validacao
    class E sucesso

    class BSim respostaSim
    class BNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

Pix

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B{"Cobrança está em dia?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["PAYMENT_RECEIVED"]
    BNao --> D["PAYMENT_OVERDUE"]
    D --> C

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B decisao
    class D validacao
    class C sucesso

    class BSim respostaSim
    class BNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

Cartão de crédito

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B{"Cobrança está em dia?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["PAYMENT_CONFIRMED"]
    BNao --> D["PAYMENT_OVERDUE"]
    D --> C
    C --> E["Aguardar 32 dias"]
    E --> F["PAYMENT_RECEIVED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B decisao
    class C,D,E validacao
    class F sucesso

    class BSim respostaSim
    class BNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

Cartão de débito

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B{"Cobrança está em dia?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["PAYMENT_CONFIRMED"]
    BNao --> D["PAYMENT_OVERDUE"]
    D --> C
    C --> E["Aguardar 3 dias"]
    E --> F["PAYMENT_RECEIVED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B decisao
    class C,D,E validacao
    class F sucesso

    class BSim respostaSim
    class BNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

Quando a cobrança estiver vencida antes do pagamento, o fluxo inclui o evento PAYMENT_OVERDUE.

Fluxos de estorno

Cartão — estorno durante a confirmação

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

    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 validacao
    class C sucesso

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

Cartão — estorno após o recebimento

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PAYMENT_CONFIRMED"]
    B --> C["PAYMENT_RECEIVED"]
    C --> D["PAYMENT_REFUNDED"]

    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

Boleto ou Pix — estorno após o recebimento

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

    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 validacao
    class C sucesso

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

Fluxo de chargeback

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PAYMENT_CONFIRMED<br/>ou PAYMENT_RECEIVED"]
    B --> C["PAYMENT_CHARGEBACK_<br/>REQUESTED"]
    C --> D{"Disputa foi aberta?"}

    D --> DSim(("Sim"))
    D --> DNao(("Não"))

    DSim --> E["PAYMENT_CHARGEBACK_<br/>DISPUTE"]
    DNao --> Z["PAYMENT_REFUNDED"]

    E --> F{"Quem venceu?"}

    F --> FAsaas(("Cliente Asaas"))
    F --> FCliente(("Cliente"))

    FAsaas --> G["PAYMENT_AWAITING_<br/>CHARGEBACK_REVERSAL"]
    G --> H["PAYMENT_CONFIRMED<br/>ou PAYMENT_RECEIVED"]

    FCliente --> Z

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class D,F decisao
    class B,C,E,G validacao
    class H,Z sucesso

    class DSim,FAsaas respostaSim
    class DNao,FCliente respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 3 stroke:#22C55E,stroke-width:4px
    linkStyle 4 stroke:#EF4444,stroke-width:4px
    linkStyle 8 stroke:#22C55E,stroke-width:4px
    linkStyle 9 stroke:#EF4444,stroke-width:4px

Quando a disputa é vencida pelo cliente Asaas, o evento posterior a PAYMENT_AWAITING_CHARGEBACK_REVERSAL será PAYMENT_CONFIRMED ou PAYMENT_RECEIVED, conforme a cobrança já tenha atingido ou não a data de crédito.

Recebimento em dinheiro e negativação

Recebimento em dinheiro

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

    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

No recebimento em dinheiro, billingType será RECEIVED_IN_CASH.

Enquanto a negativação ainda estiver em processamento, o último evento do fluxo será PAYMENT_DUNNING_REQUESTED. Quando o recebimento da negativação ocorrer, será enviado PAYMENT_DUNNING_RECEIVED.

Eventos como PAYMENT_DELETED, PAYMENT_RESTORED, PAYMENT_BANK_SLIP_VIEWED e PAYMENT_CHECKOUT_VIEWED também podem ocorrer, mas não fazem parte dos fluxos de recebimento apresentados acima.

Próximos passos

Updated about 8 hours ago

Did this page help you?