Events for Checkout

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

Use Checkout events to track the result of the payment journey and synchronize your order, subscription, or service with Asaas.

Each notification provides the event that occurred in event and the current Checkout data in the checkout object.

Available events

Event	When it occurs
`CHECKOUT_CREATED`	The Checkout is created.
`CHECKOUT_PAID`	The Checkout is paid.
`CHECKOUT_CANCELED`	The Checkout is canceled.
`CHECKOUT_EXPIRED`	The Checkout expires.

How to interpret the events

Event	Handling in the integration
`CHECKOUT_CREATED`	Register the Checkout and associate `checkout.id` with the corresponding order or process.
`CHECKOUT_PAID`	Confirm the payment and update the order, subscription, or service.
`CHECKOUT_CANCELED`	Update the journey as canceled.
`CHECKOUT_EXPIRED`	Update the journey as expired and prevent the Checkout from being treated as active.

Do not use the callback URLs to confirm the payment. They control the payer's redirect; use CHECKOUT_PAID to confirm the Checkout result.

See how to configure the Checkout link and redirect.

Configure the Checkout events

The configuration uses the standard Webhooks endpoint:

POST /v3/webhooks

Authenticate the request by sending your API Key in the access_token header.

In events, configure only the Checkout events your integration needs.

{
  "name": "test",
  "url": "https://my-url.com",
  "email": "[email protected]",
  "enabled": true,
  "interrupted": false,
  "apiVersion": 3,
  "authToken": "secure-token-with-more-than-32-characters",
  "sendType": "SEQUENTIALLY",
  "events": [
    "CHECKOUT_CREATED",
    "CHECKOUT_CANCELED",
    "CHECKOUT_EXPIRED",
    "CHECKOUT_PAID"
  ]
}

In the notifications sent by Asaas, the configured authToken is sent in the asaas-access-token header. This is different from the access_token header, which you use to authenticate your own requests to the API.

See how to create a Webhook through the API.

Event payload

After configuration, Asaas sends a POST request to the registered URL.

{
  "id": "evt_37260be8159d4472b4458d3de13efc2d&15370",
  "event": "CHECKOUT_CREATED",
  "dateCreated": "2024-10-31 18:07:47",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "checkout": {
    "id": "2bd251f0-09b2-44ff-8a0c-a5cb29e5bbda",
    "link": null,
    "status": "ACTIVE",
    "minutesToExpire": 10,
    "billingTypes": [
      "MUNDIPAGG_CIELO"
    ],
    "chargeTypes": [
      "RECURRENT"
    ],
    "callback": {
      "cancelUrl": "https://google.com",
      "successUrl": "https://google.com",
      "expiredUrl": "https://google.com"
    },
    "items": [
      {
        "name": "test2",
        "description": "test",
        "quantity": 2,
        "value": 100
      },
      {
        "name": "test2",
        "description": "test2",
        "quantity": 2,
        "value": 100
      }
    ],
    "subscription": {
      "cycle": "MONTHLY",
      "nextDueDate": "2024-10-31T03:00:00+0000",
      "endDate": "2025-10-29T03:00:00+0000"
    },
    "installment": null,
    "split": [
      {
        "walletId": "c1ad713f-77fc-45b0-b734-b2ff9970d6d8",
        "fixedValue": 2,
        "percentualValue": null,
        "totalFixedValue": null
      },
      {
        "walletId": "c1ad713f-77fc-45b0-b734-b2ff9970d6d8",
        "fixedValue": null,
        "percentualValue": 2,
        "totalFixedValue": null
      }
    ],
    "customer": "cus_000000018936",
    "customerData": null
  }
}

Important payload fields

Field	Description
`id`	Unique event identifier. Use it for idempotency.
`event`	Identifies the event received.
`checkout.id`	Checkout identifier.
`checkout.status`	Current status of the Checkout.
`checkout.minutesToExpire`	Configured expiration time.
`checkout.billingTypes`	Available payment methods.
`checkout.chargeTypes`	Available charge types.
`checkout.callback`	Payer redirect URLs.
`checkout.customer`	Customer associated with the Checkout, when provided.

event identifies the change notified by the Webhook. checkout.status represents the current status of the Checkout in the payload.

How to handle the events

The recommended processing is:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
  A["Receive the event"] --> B["Validate the request"]
  B --> C["Persist the event"]
  C --> D["Respond HTTP 200"]
  D --> E["Process the event"]
  E --> F["Update the application"]

  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,D,E validacao
  class F sucesso

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

Webhooks follow the at least once model, so the same event may be sent more than once. Use the event id to implement idempotency.

When using authToken, validate the asaas-access-token header before processing the notification.

If sendType is set to SEQUENTIALLY, events are sent in the order in which they occurred. For other delivery behaviors, see Delivery Types.

See how to implement idempotency 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 not handled by your application, as this may interrupt the synchronization 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 defined in the Webhook settings.

Next steps

Updated 13 days ago

Did this page help you?