Eventos para recargas de celular

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

Use os eventos de recarga de celular para acompanhar automaticamente o processamento das recargas realizadas pelo Asaas.

Cada notificação informa o evento ocorrido em event e os dados atuais da recarga no objeto mobilePhoneRecharge.

Eventos disponíveis

Evento	Quando ocorre
`MOBILE_PHONE_RECHARGE_PENDING`	A recarga está pendente.
`MOBILE_PHONE_RECHARGE_CONFIRMED`	A recarga é confirmada.
`MOBILE_PHONE_RECHARGE_CANCELLED`	A recarga é cancelada.
`MOBILE_PHONE_RECHARGE_REFUNDED`	A recarga é estornada.

Como interpretar os eventos

Evento	Tratamento na integração
`MOBILE_PHONE_RECHARGE_PENDING`	Mantenha a recarga como pendente enquanto aguarda o processamento.
`MOBILE_PHONE_RECHARGE_CONFIRMED`	Confirme a recarga no seu sistema e atualize o usuário, quando aplicável.
`MOBILE_PHONE_RECHARGE_CANCELLED`	Atualize a operação como cancelada.
`MOBILE_PHONE_RECHARGE_REFUNDED`	Atualize a operação para refletir o estorno.

event identifica a alteração notificada pelo Webhook. mobilePhoneRecharge.status representa a situação atual da recarga no payload.

Fluxos da recarga

Recarga confirmada

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["MOBILE_PHONE_RECHARGE_<br/>PENDING"] --> B["MOBILE_PHONE_RECHARGE_<br/>CONFIRMED"]

    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

Recarga cancelada

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["MOBILE_PHONE_RECHARGE_<br/>PENDING"] --> B["MOBILE_PHONE_RECHARGE_<br/>CANCELLED"]

    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

Recarga estornada

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["MOBILE_PHONE_RECHARGE_<br/>CONFIRMED"] --> B["MOBILE_PHONE_RECHARGE_<br/>REFUNDED"]

    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

Os fluxos acima representam os cenários atualmente documentados para recargas. Trate cada evento recebido conforme seu tipo, sem depender de consultas periódicas à API para acompanhar mudanças de estado.

Payload do evento

A notificação é enviada via POST com o evento e os dados da recarga.

{
   "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
   "event": "MOBILE_PHONE_RECHARGE_CONFIRMED",
   "dateCreated": "2024-06-12 16:45:03",
   "account": {
      "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
      "ownerId": null
   },
   "mobilePhoneRecharge": {
      "id": "29ad50e9-64ee-427e-a00c-a3999510ca0a",
      "value": 15,
      "phoneNumber": "62982055478",
      "status": "CONFIRMED",
      "canBeCancelled": false,
      "operatorName": "Tim"
   }
}

Campos importantes do payload

Campo	Descrição
`id`	Identificador único do evento. Utilize-o para idempotência.
`event`	Identifica o evento recebido.
`mobilePhoneRecharge.id`	Identificador da recarga.
`mobilePhoneRecharge.status`	Situação atual da recarga.
`mobilePhoneRecharge.value`	Valor da recarga.
`mobilePhoneRecharge.phoneNumber`	Número recarregado.
`mobilePhoneRecharge.operatorName`	Operadora da linha.
`mobilePhoneRecharge.canBeCancelled`	Indica se a recarga ainda pode ser cancelada.

👍
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 recarga de celular" na documentação.

Como tratar os eventos

Ao receber um evento de recarga:

identifique a alteração pelo campo event;
persista o id para impedir processamento duplicado;
utilize mobilePhoneRecharge.id para localizar a recarga no seu sistema;
atualize a operação conforme event e mobilePhoneRecharge.status;
responda HTTP 200 após confirmar a persistência;
processe regras adicionais de forma assíncrona.

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez.

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 2 days ago

Did this page help you?