Mobile phone recharge events

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

Use mobile phone recharge events to automatically track the processing of recharges made through Asaas.

Each notification indicates the event that occurred in event and the current recharge data in the mobilePhoneRecharge object.

Available events

Event	When it occurs
`MOBILE_PHONE_RECHARGE_PENDING`	The recharge is pending.
`MOBILE_PHONE_RECHARGE_CONFIRMED`	The recharge is confirmed.
`MOBILE_PHONE_RECHARGE_CANCELLED`	The recharge is cancelled.
`MOBILE_PHONE_RECHARGE_REFUNDED`	The recharge is refunded.

How to interpret the events

Event	Handling in the integration
`MOBILE_PHONE_RECHARGE_PENDING`	Keep the recharge as pending while it awaits processing.
`MOBILE_PHONE_RECHARGE_CONFIRMED`	Confirm the recharge in your system and update the user, when applicable.
`MOBILE_PHONE_RECHARGE_CANCELLED`	Update the operation as cancelled.
`MOBILE_PHONE_RECHARGE_REFUNDED`	Update the operation to reflect the refund.

event identifies the change notified by the Webhook. mobilePhoneRecharge.status represents the current status of the recharge in the payload.

Recharge flows

Recharge confirmed

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

Recharge cancelled

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

Recharge refunded

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

The flows above represent the scenarios currently documented for recharges. Handle each event received according to its type, without relying on periodic API queries to track state changes.

Event payload

The notification is sent via POST with the event and the recharge data.

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

Important payload fields

Field	Description
`id`	Unique identifier of the event. Use it for idempotence.
`event`	Identifies the event received.
`mobilePhoneRecharge.id`	Recharge identifier.
`mobilePhoneRecharge.status`	Current status of the recharge.
`mobilePhoneRecharge.value`	Recharge amount.
`mobilePhoneRecharge.phoneNumber`	Recharged number.
`mobilePhoneRecharge.operatorName`	Carrier of the phone line.
`mobilePhoneRecharge.canBeCancelled`	Indicates whether the recharge can still be cancelled.

👍
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 mobile phone recharge" endpoint in the documentation.

How to handle the events

When receiving a recharge event:

identify the change through the event field;
persist the id to prevent duplicate processing;
use mobilePhoneRecharge.id to find the recharge in your system;
update the operation according to event and mobilePhoneRecharge.status;
respond HTTP 200 after confirming persistence;
process additional rules asynchronously.

Webhooks follow the at least once model, so the same event may be sent more than once.

See how to implement idempotence 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 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.

Next steps

Updated 6 days ago

Did this page help you?