Events for mobile top-ups

You can use Webhooks so that your system is notified about changes that occur in mobile top-ups.

The events notified by Asaas are:

• MOBILE_PHONE_RECHARGE_PENDING - Mobile top-up pending.
• MOBILE_PHONE_RECHARGE_CANCELLED - Mobile top-up canceled.
• MOBILE_PHONE_RECHARGE_CONFIRMED - Mobile top-up confirmed.
• MOBILE_PHONE_RECHARGE_REFUNDED - Mobile top-up refunded.

When to use

Mobile top-up Webhooks are recommended when your application needs to automatically track the processing of top-ups performed through Asaas.

Some examples:

• updating internal systems;
• tracking top-up status;
• financial auditing;
• synchronization with ERPs;
• user notifications.

Important behaviors

Asaas Webhooks use the at least once delivery model, therefore the same event may be sent more than once.

For this reason, it is recommended to implement idempotency using the event identifier:

id

In addition:

• HTTP responses outside the 2xx family may trigger new delivery attempts;
• the queue may be interrupted after consecutive failures;
• events remain stored for up to 14 days;
• new attributes may be added in the future.

Common event flow

The flow usually occurs as follows:

MOBILE_PHONE_RECHARGE_PENDING
↓
MOBILE_PHONE_RECHARGE_CONFIRMED

In specific situations, the following may also occur:

MOBILE_PHONE_RECHARGE_PENDING
↓
MOBILE_PHONE_RECHARGE_CANCELLED

or

MOBILE_PHONE_RECHARGE_CONFIRMED
↓
MOBILE_PHONE_RECHARGE_REFUNDED

Example JSON received [POST]

The notification consists of a POST containing a JSON, as shown below:

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

👍

Webhook response with typing 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 mobile top-up" in the documentation.

Best practices

We recommend:

• validating the asaas-access-token header;
• responding quickly using HTTP 2xx status codes;
• implementing idempotency using the id field;
• processing events asynchronously;
• continuously monitoring Webhook Logs;
• preparing the application to accept new attributes without throwing exceptions.

Common errors

Duplicate event

Since delivery follows the at least once model, the same event may be resent.

Use the event identifier to avoid duplicate processing.

HTTP response outside the 2xx range

Responses outside the 2xx family may trigger new delivery attempts.

New fields in the payload

Your application should ignore unknown fields to maintain compatibility with future versions.

Operational impacts

Failures in Webhook processing may cause:

• new delivery attempts;
• synchronization queue interruption;
• inconsistencies between systems;
• delays in updating top-up status;
• permanent event loss after 14 days.

🚧

Attention

• As new products and features are introduced in Asaas, new attributes may be added to 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 cause interruption of the synchronization queue.
• We will send an email and notify our Discord whenever new fields are added to the Webhook. Notifications will be sent to the email address configured in the Webhook settings.