DiscordStatus
Guias / Guides

Events for Payments

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

Webhooks are the best and safest way to keep your application's data synchronized with Asaas. Whenever a payment changes status, a new event is generated and delivered to your endpoint.

The events notified by Asaas are:

  • PAYMENT_CREATED - New payment created.
  • PAYMENT_AWAITING_RISK_ANALYSIS - Card payment awaiting manual risk analysis approval.
  • 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 and awaiting capture.
  • PAYMENT_UPDATED - Existing payment due date or amount changed.
  • PAYMENT_CONFIRMED - Payment confirmed (payment completed, but funds are not yet available).
  • PAYMENT_RECEIVED - Payment received (funds available in the Asaas account).
  • PAYMENT_CREDIT_CARD_CAPTURE_REFUSED - Credit card payment failed.
  • PAYMENT_ANTICIPATED - Payment anticipated.
  • PAYMENT_OVERDUE - Payment overdue.
  • PAYMENT_DELETED - Payment deleted.
  • PAYMENT_RESTORED - Payment restored.
  • PAYMENT_REFUNDED - Payment refunded.
  • PAYMENT_PARTIALLY_REFUNDED - Payment partially refunded.
  • PAYMENT_REFUND_IN_PROGRESS - Refund in progress (settlement already scheduled; the payment will be refunded after settlement).
  • PAYMENT_REFUND_DENIED - Refund denied (bank slips only).
  • PAYMENT_RECEIVED_IN_CASH_UNDONE - Cash payment reversal.
  • PAYMENT_CHARGEBACK_REQUESTED - Chargeback received.
  • PAYMENT_CHARGEBACK_DISPUTE - Chargeback dispute in progress (documents submitted for contestation).
  • PAYMENT_AWAITING_CHARGEBACK_REVERSAL - Dispute won, awaiting acquirer settlement.
  • PAYMENT_DUNNING_RECEIVED - Credit bureau registration received.
  • PAYMENT_BANK_SLIP_CANCELLED - Bank slip registration canceled due to payment expiration after the due date. (It does not indicate payment deletion, only cancellation of the bank slip registration in CIP).
  • PAYMENT_DUNNING_REQUESTED - Credit bureau registration requested.
  • PAYMENT_BANK_SLIP_VIEWED - Bank slip viewed by the customer.
  • PAYMENT_CHECKOUT_VIEWED - Payment invoice viewed by the customer.
  • PAYMENT_SPLIT_CANCELLED - A payment had a split canceled.
  • PAYMENT_SPLIT_DIVERGENCE_BLOCK - Payment amount blocked due to split divergence.
  • PAYMENT_SPLIT_DIVERGENCE_BLOCK_FINISHED - Split divergence block completed.

Whenever a payment Webhook is sent, a JSON object containing the complete payment information is sent via POST, as shown below:

{
   "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"
   }
}
📘

Optional fields

  • subscription: returned only when the payment belongs to a subscription.
  • installment: returned only when the payment belongs to an installment.
  • paymentLink: identifier of the payment link that originated the payment.
  • originalValue: returned when the amount effectively paid differs from the original amount.
  • The split array is returned only for payments 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 endpoint "Retrieve a single payment" in the documentation.

Everything in Asaas is considered a payment, including direct bank transfers, deposits, and Pix receipts. Therefore, you will receive Payment Webhooks for any amount credited to your account.

🚧

Attention

  • As new products and features are introduced in Asaas, new attributes may be added to Webhooks. It is extremely important that your code is prepared to handle additional attributes without throwing exceptions, as this may cause interruption of the synchronization queue.

  • We will send an email and announce it on our Discord whenever new fields are added to the Webhook. Notifications are sent to the email configured in the Webhook settings.

  • The split array is returned only when the payment has Payment Split configured.

How does the payment Webhook flow work?

Below are some examples of payment flows:

Bank slip payment received on time:
PAYMENT_CREATED → PAYMENT_CONFIRMED → PAYMENT_RECEIVED

Bank slip payment received after due date:
PAYMENT_CREATED → PAYMENT_OVERDUE → PAYMENT_CONFIRMED → PAYMENT_RECEIVED

Pix payment received on time:
PAYMENT_CREATED → PAYMENT_RECEIVED

Pix payment received after due date:
PAYMENT_CREATED → PAYMENT_OVERDUE → PAYMENT_RECEIVED

Credit card payment received on time:
PAYMENT_CREATED → PAYMENT_CONFIRMED → PAYMENT_RECEIVED (32 days after PAYMENT_CONFIRMED)

Debit card payment received on time:
PAYMENT_CREATED → PAYMENT_CONFIRMED → PAYMENT_RECEIVED (3 days after PAYMENT_CONFIRMED)

Credit card payment received after due date:
PAYMENT_CREATED → PAYMENT_OVERDUE → PAYMENT_CONFIRMED → PAYMENT_RECEIVED (32 days after PAYMENT_CONFIRMED)

Debit card payment received after due date:
PAYMENT_CREATED → PAYMENT_OVERDUE → PAYMENT_CONFIRMED → PAYMENT_RECEIVED (3 days after PAYMENT_CONFIRMED)

Payment refunded during confirmation phase (Credit/Debit Card):
PAYMENT_CREATED → PAYMENT_CONFIRMED → PAYMENT_REFUNDED

Payment refunded after funds are available (Credit/Debit Card):
PAYMENT_CREATED → PAYMENT_CONFIRMED → PAYMENT_RECEIVED → PAYMENT_REFUNDED

Payment refunded after funds are available (Bank Slip/Pix):
PAYMENT_CREATED → PAYMENT_RECEIVED → PAYMENT_REFUNDED

Chargeback requested, dispute opened and won by the Asaas customer:
PAYMENT_CREATED → PAYMENT_CONFIRMED or PAYMENT_RECEIVED → PAYMENT_CHARGEBACK_REQUESTED → PAYMENT_CHARGEBACK_DISPUTE → PAYMENT_AWAITING_CHARGEBACK_REVERSAL → PAYMENT_CONFIRMED or PAYMENT_RECEIVED (depending on whether the credit date has been reached).

Chargeback requested, dispute opened and won by the cardholder:
PAYMENT_CREATED → PAYMENT_CONFIRMED or PAYMENT_RECEIVED → PAYMENT_CHARGEBACK_REQUESTED → PAYMENT_CHARGEBACK_DISPUTE → PAYMENT_REFUNDED

Chargeback requested without dispute:
PAYMENT_CREATED → PAYMENT_CONFIRMED or PAYMENT_RECEIVED → PAYMENT_CHARGEBACK_REQUESTED → PAYMENT_REFUNDED

Cash payment confirmed:
PAYMENT_CREATED → PAYMENT_RECEIVED (billingType will be RECEIVED_IN_CASH).

Serasa credit bureau process initiated:
PAYMENT_CREATED → PAYMENT_OVERDUE → PAYMENT_DUNNING_REQUESTED

Serasa credit bureau process completed:
PAYMENT_CREATED → PAYMENT_OVERDUE → PAYMENT_DUNNING_REQUESTED → PAYMENT_DUNNING_RECEIVED

It is important to emphasize that whenever a payment becomes overdue, it will pass through the PAYMENT_OVERDUE status.

Occasionally, other events may also be triggered, such as PAYMENT_DELETED, PAYMENT_RESTORED, PAYMENT_BANK_SLIP_VIEWED, and PAYMENT_CHECKOUT_VIEWED. However, these events are not directly related to payment collection flows.