Payment events

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

Payment events

Use payment events to track changes related to charges, payments received, refunds, chargebacks, dunning (negativação) and Split.

Each notification is sent by Webhook with the event type in event and the charge data in the payment object.

Available events

Charge and payment lifecycle

Event	When it occurs
`PAYMENT_CREATED`	A new charge is generated.
`PAYMENT_AWAITING_RISK_ANALYSIS`	Card payment awaiting approval by manual risk analysis.
`PAYMENT_APPROVED_BY_RISK_ANALYSIS`	Card payment approved by manual risk analysis.
`PAYMENT_REPROVED_BY_RISK_ANALYSIS`	Card payment rejected by manual risk analysis.
`PAYMENT_AUTHORIZED`	Card payment authorized that needs to be captured.
`PAYMENT_UPDATED`	Change to the due date or value of an existing charge.
`PAYMENT_CONFIRMED`	Payment made, but the balance is not yet available.
`PAYMENT_RECEIVED`	Charge received, with the amount available in the Asaas account.
`PAYMENT_CREDIT_CARD_CAPTURE_REFUSED`	Failure to capture the credit card payment.
`PAYMENT_ANTICIPATED`	Charge anticipated.
`PAYMENT_OVERDUE`	Charge overdue.
`PAYMENT_DELETED`	Charge removed.
`PAYMENT_RESTORED`	Charge restored.

Refunds and chargebacks

Event	When it occurs
`PAYMENT_REFUNDED`	Charge refunded.
`PAYMENT_PARTIALLY_REFUNDED`	Charge partially refunded.
`PAYMENT_REFUND_IN_PROGRESS`	Refund in progress. The settlement is already scheduled and the charge will be refunded after it is executed.
`PAYMENT_REFUND_DENIED`	Refund denied. Available only for bank slips (boletos).
`PAYMENT_RECEIVED_IN_CASH_UNDONE`	Cash receipt undone.
`PAYMENT_CHARGEBACK_REQUESTED`	Chargeback received.
`PAYMENT_CHARGEBACK_DISPUTE`	Chargeback under dispute after documents were submitted to contest it.
`PAYMENT_AWAITING_CHARGEBACK_REVERSAL`	Dispute won, awaiting transfer from the acquirer.

Bank slip, dunning and viewing

Event	When it occurs
`PAYMENT_DUNNING_REQUESTED`	Dunning (negativação) request.
`PAYMENT_DUNNING_RECEIVED`	Dunning (negativação) payment received.
`PAYMENT_BANK_SLIP_CANCELLED`	Bank slip registration cancelled after the due date because the account is configured not to allow payment of overdue charges. It does not indicate that the charge was removed.
`PAYMENT_BANK_SLIP_VIEWED`	The charge's bank slip was viewed by the customer.
`PAYMENT_CHECKOUT_VIEWED`	The charge's invoice was viewed by the customer.

📘
Bank slip registration cancellation
The PAYMENT_BANK_SLIP_CANCELLED event is sent when the bank slip registration is cancelled after the due date because the account is configured not to allow payment of overdue charges.
The daysAfterDueDateToRegistrationCancellation field does not trigger this event. Although this field determines for how many days after the due date the bank slip registration remains available for payment, the cancellation resulting from this setting does not generate PAYMENT_BANK_SLIP_CANCELLED.

Split

Event	When it occurs
`PAYMENT_SPLIT_CANCELLED`	A Split of the charge was cancelled.
`PAYMENT_SPLIT_DIVERGENCE_BLOCK`	Charge amount blocked due to a Split divergence.
`PAYMENT_SPLIT_DIVERGENCE_BLOCK_FINISHED`	Block due to Split divergence finished.
`PAYMENT_SPLIT_DONE`	A Split of the charge was settled.

📘
Split cancellation by withdrawal validation
The PAYMENT_SPLIT_CANCELLED event is not sent when the Split is cancelled by the Withdrawal validation mechanism via webhooks, whether due to refusal (REFUSED), a response without a valid status, or a failure when calling your Webhook.
In this case, check the Split's cancellationReason field through the API to identify the reason for the cancellation.

Event payload

Each payment event is sent via POST with the charge data.

Example:

{
   "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":"Order 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
   }
}

📘
Optional fields

subscription: returned only when the charge belongs to a subscription.

installment: returned only when the charge belongs to an installment.

paymentLink: identifier of the payment link that originated the charge.

originalValue: returned when the amount actually paid differs from the original charge value.

The split array is returned only for charges with Payment Split configured.

👍
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 payment" endpoint in the documentation.

When an amount enters the Asaas account, the revenue is associated with a charge. This also happens for receipts created automatically from Pix or TED.

See how Asaas handles revenue in the account.

🚧
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.

The split array will be returned only when the charge has Payment Split settings.

Payment flows

The events received vary according to the payment method and the charge's due date.

Bank slip (boleto)

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B{"Is the charge on time?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    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{"Is the charge on time?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    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

Credit card

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B{"Is the charge on time?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BSim --> C["PAYMENT_CONFIRMED"]
    BNao --> D["PAYMENT_OVERDUE"]
    D --> C
    C --> E["Wait 32 days"]
    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

Debit card

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B{"Is the charge on time?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BSim --> C["PAYMENT_CONFIRMED"]
    BNao --> D["PAYMENT_OVERDUE"]
    D --> C
    C --> E["Wait 3 days"]
    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

When the charge is overdue before payment, the flow includes the PAYMENT_OVERDUE event.

Refund flows

Card — refund during confirmation

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

Card — refund after receipt

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

Bank slip or Pix — refund after receipt

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

Chargeback flow

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PAYMENT_CONFIRMED<br/>or PAYMENT_RECEIVED"]
    B --> C["PAYMENT_CHARGEBACK_<br/>REQUESTED"]
    C --> D{"Was a dispute opened?"}

    D --> DSim(("Yes"))
    D --> DNao(("No"))

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

    E --> F{"Who won?"}

    F --> FAsaas(("Asaas customer"))
    F --> FCliente(("Customer"))

    FAsaas --> G["PAYMENT_AWAITING_<br/>CHARGEBACK_REVERSAL"]
    G --> H["PAYMENT_CONFIRMED<br/>or 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

When the dispute is won by the Asaas customer, the event after PAYMENT_AWAITING_CHARGEBACK_REVERSAL will be PAYMENT_CONFIRMED or PAYMENT_RECEIVED, depending on whether the charge has already reached its credit date.

Cash receipt and dunning

Cash receipt

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

For cash receipts, billingType will be RECEIVED_IN_CASH.

While dunning (negativação) is still being processed, the last event in the flow will be PAYMENT_DUNNING_REQUESTED. When the dunning payment is received, PAYMENT_DUNNING_RECEIVED will be sent.

Events such as PAYMENT_DELETED, PAYMENT_RESTORED, PAYMENT_BANK_SLIP_VIEWED and PAYMENT_CHECKOUT_VIEWED may also occur, but they are not part of the payment flows shown above.

Next steps

Updated 3 days ago

Did this page help you?