Eventos para Checkout

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

Use os eventos de Checkout para acompanhar o resultado da jornada de pagamento e sincronizar seu pedido, assinatura ou serviço com o Asaas.

Cada notificação informa o evento ocorrido em event e os dados atuais do Checkout no objeto checkout.

Eventos disponíveis

Evento	Quando ocorre
`CHECKOUT_CREATED`	O Checkout é criado.
`CHECKOUT_PAID`	O Checkout é pago.
`CHECKOUT_CANCELED`	O Checkout é cancelado.
`CHECKOUT_EXPIRED`	O Checkout expira.

Como interpretar os eventos

Evento	Tratamento na integração
`CHECKOUT_CREATED`	Registre o Checkout e associe `checkout.id` ao pedido ou processo correspondente.
`CHECKOUT_PAID`	Confirme o pagamento e atualize o pedido, assinatura ou serviço.
`CHECKOUT_CANCELED`	Atualize a jornada como cancelada.
`CHECKOUT_EXPIRED`	Atualize a jornada como expirada e impeça que o Checkout seja tratado como ativo.

Não utilize as URLs de callback para confirmar o pagamento. Elas controlam o redirecionamento do pagador; utilize CHECKOUT_PAID para confirmar o resultado do Checkout.

Consulte como configurar o link e o redirecionamento do Checkout.

Configure os eventos do Checkout

A configuração utiliza o endpoint padrão de Webhooks:

POST /v3/webhooks

Autentique a requisição utilizando a API Key no header:

access_token

Configure em events somente os eventos de Checkout necessários para sua integração.

{
  "name": "teste",
  "url": "https://minha-url.com",
  "email": "[email protected]",
  "enabled": true,
  "interrupted": false,
  "apiVersion": 3,
  "authToken": "token-seguro-com-mais-de-32-caracteres",
  "sendType": "SEQUENTIALLY",
  "events": [
    "CHECKOUT_CREATED",
    "CHECKOUT_CANCELED",
    "CHECKOUT_EXPIRED",
    "CHECKOUT_PAID"
  ]
}

O authToken configurado será enviado nas notificações pelo header asaas-access-token.

Consulte como criar um Webhook pela API.

Payload do evento

Após a configuração, o Asaas envia uma requisição POST para a URL cadastrada.

{
  "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": "teste2",
        "description": "teste",
        "quantity": 2,
        "value": 100
      },
      {
        "name": "teste2",
        "description": "teste2",
        "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
  }
}

Campos importantes do payload

Campo	Descrição
`id`	Identificador único do evento. Utilize-o para idempotência.
`event`	Identifica o evento recebido.
`checkout.id`	Identificador do Checkout.
`checkout.status`	Situação atual do Checkout.
`checkout.minutesToExpire`	Tempo configurado para expiração.
`checkout.billingTypes`	Formas de pagamento disponíveis.
`checkout.chargeTypes`	Tipos de cobrança disponíveis.
`checkout.callback`	URLs de redirecionamento do pagador.
`checkout.customer`	Cliente associado ao Checkout, quando informado.

event identifica a alteração notificada pelo Webhook. checkout.status representa a situação atual do Checkout no payload.

Como tratar os eventos

O processamento recomendado é:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Receber o evento"] --> B["Validar a requisição"]
    B --> C["Persistir o evento"]
    C --> D["Responder HTTP 200"]
    D --> E["Processar o evento"]
    E --> F["Atualizar a aplicação"]

    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

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez. Utilize o id do evento para implementar idempotência.

Quando utilizar authToken, valide o header asaas-access-token antes de processar a notificação.

Se sendType estiver configurado como SEQUENTIALLY, os eventos são enviados respeitando a ordem em que ocorreram. Para outros comportamentos de entrega, consulte Tipos de envio.

Consulte como implementar idempotência em Webhooks.

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

Próximos passos

Updated 14 days ago

Did this page help you?