Skip to main content

Notifications

Learn more about how Efí's notification system works


Receiving Notifications​

Notifications allow you to receive information when the status of a transaction changes, such as when a boleto is paid, for example.

When a transaction has a registered notification URL (attribute notification_url), Efí sends a POST to this URL each time the status of the charge changes. This notification has a specific token, which will remain the same throughout the entire "cycle of changes" of the transaction. For example:

  • A charge is generated. Your system receives a POST from Efí containing the notification token 09027955-5e06-4ff0-a9c7-46b47b8f1b27 and informing the transaction status - in this case, new;

  • This same charge had the payment method defined, so its status changed to waiting and, subsequently, we will send a new notification to your system containing the same token 09027955-5e06-4ff0-a9c7-46b47b8f1b27;

  • Later, this same charge had the payment confirmed, so the status changes to paid and again your system receives a notification, still with the same token 09027955-5e06-4ff0-a9c7-46b47b8f1b27.

banner

Example of how to simulate the token sending request via Postman

A POST will contain only one piece of information: a notification token. This token is sent when there is a change in the charge status. To receive these notifications, you need to register a notification URL in the charge and prepare it to read the token in the $_POST['notification'] variable.

For security reasons, the transaction information will only be sent when your system queries it using the received notification token.

At any time the integrator queries this notification token, they will obtain the most current charge information, all ordered according to the events. Every status change generates a notification.

In the Histórico de Notificações tab, it is possible to track all the notification POST requests sent by our system. When the integrator queries the sent token, we consider that the notification was successfully received. If it is not queried, we will try to send the notification again.

For details on implementation and the necessary procedures, you can find more information in our documentation and install one of our libraries on your server to run the example codes.


Setting up the URL to Receive Notifications​

You can define a URL that will receive notifications during the creation of the charge (createCharge) or later (updateChargeMetadata).

A transaction generated through the API can undergo various status changes based on interactions from the payer, the integrating party, or the involved banks and financial institutions. To track these changes, you need to prepare your system to receive notifications sent by Efí.

When setting the parameters for creating the transaction, you can provide a notification URL. This URL will receive a token whenever there is a status change in the transaction. With this token, your application can query our web service to obtain the updated status of the transaction.

$options = [
  'client_id' => $clientId,
  'client_secret' => $clientSecret,
  'sandbox' => true
],

$metadata = array('notification_url'=>'http://sua_url_aqui');

$body = [
  'items' => $items,
  'metadata' => $metadata
];

try {
  $api = new Efí($options);
  $charge = $api->createCharge([], $body);
}

TIP FOR TESTING NOTIFICATIONS (CALLBACKS) EASILY WITH WEBHOOKINBOX

To test notifications, we suggest using WebhookInbox, a free service to inspect HTTP requests. With it, you can create a temporary URL to use in the notification_url attribute, allowing you to easily and visually see the POSTs sent to your application. To generate the request receiving URL, simply access WebhookInbox and click on Create An Inbox.

WebbookInbox will record HTTP requests and allow you to inspect them to check Headers and Body of the requests. This way, you can start developing your integration with Efí and testing the Notification URL (callbacks) features even if you don't already have a public URL available.


If you do not register a URL at the time of transaction creation, you can do so through the metadata alteration method, using a PUT request to the route /v1/charge/:id/metadata.

The notification process is carried out in two steps to ensure the security of the data provided:

  1. In the first step, your system is notified that there has been a transaction-related change (the webservice sends a POST with a token to you);

  2. In the second step, your system queries - passing the token you received as a parameter to Efí to know details about this change.

Consulting details of a notification​

Efí considers that a notification has been successfully carried out only after this query. As long as your system does not consult the notification details, it will continue to be notified:

<?php
 
require __DIR__.'/../../vendor/autoload.php'; // SDK related path
 
use Efí\Exception\EfíException;
use Efí\Efí;
 
$clientId = 'inform_your_client_id'; // enter your Client_Id, depending on the environment (Des or Prod)
$clientSecret = 'inform_your_client_secret'; // enter your Client_Secret, depending on the environment (Des or Prod)
 
$options = [
  'client_id' => $clientId,
  'client_secret' => $clientSecret,
  'sandbox' => true // change depending on the environment (true = development and false = production)
];
 
/*
* This token will be received in your variable representing the POST parameters.
* E.g.: $_POST['notification']
*/
$token = $_POST["notification"];
 
$params = [
  'token' => $token
];
 
try {
    $api = new Efí($options);
    $chargeNotification = $api->getNotification($params, []);
  // To identify the current status of your transaction you must count the number of situations contained in the array, because the last position always holds the last status. See a sample response in the "Sample responses" section below.
  
  // See below for how to access the ID and String referring to the last status of the transaction.
    
    // Count the size of the data array (which stores the result)
    $i = count($chargeNotification["data"]);
     // Get the last chargeStatus object
    $ultimoStatus = $chargeNotification["data"][$i-1];
     // Accessing the Status array
    $status = $ultimoStatus["status"];
    // Getting the transaction ID       
    $charge_id = $ultimoStatus["identifiers"]["charge_id"];
    // Getting the current status string
    $statusAtual = $status["current"];
    
     // With this information, you can query your database and update the status of the specific transaction, once you have the "charge_id" and the STATUS String.
  
    echo "O id da transação é: ".$charge_id." seu novo status é: ".$statusAtual;
 
    //print_r($chargeNotification);
} catch (EfíException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

Examples of responses:​

Below are some examples of notification responses for transactions, subscriptions, carnets and payment link:

{
    "code": 200, // HTTP return "200" stating that the request was successful
    "data": [
        {
            "created_at": "2022-02-20 09:12:23", // date of the status change of the "id 1" array
            "custom_id": null,
            "id": 1, // order indicator, starting at 1. It is incremented for each change of a notification token. This is useful if you need to keep track of which change you've already processed
            "identifiers": { // identifiers representing the charge
                "charge_id": 24342333
            },
            "status": {
                "current": "new",
                "previous": null
            },
            "type": "charge" // type of charge that was changed (in this case, "charge" means that the change occurred in a transaction)
        },
        {
            "created_at": "2022-02-20 09:12:23", // date of the status change of the "id 2" array
            "custom_id": null, // identifier of the charge defined by the integrator, if any
            "id": 2,
            "identifiers": { // identifiers representing the charge
                "charge_id": 24342333
            },
            "status": {
                "current": "waiting",
                "previous": "new"
            },
            "type": "charge" // type of charge that was changed (in this case, "charge" means that the change occurred in a transaction)
        },
        {
            "created_at": "2022-03-31 09:14:34", // date of the status change of the "id 3" array
            "custom_id": null, // identifier of the charge defined by the integrator, if any
            "id": 3,
            "identifiers": { // identifiers representing the charge
                "charge_id": 24342333
            },
            "status": {
                "current": "unpaid",
                "previous": "waiting"
            },
            "type": "charge" // type of charge that was changed (in this case, "charge" means that the change occurred in a transaction)
        },
        {
            "created_at": "2022-04-03 07:33:30", // date of status change for array "id 4"
            "custom_id": null, // identifier of the charge defined by the integrator, if any
            "id": 4,
            "identifiers": { // identifiers representing the charge
                "charge_id": 24342333
            },
            "received_by_bank_at": "2022-04-02", // date of payment of the charge
            "status": {
                "current": "paid", // CURRENT status of the transaction: paid ("paid")
                "previous": "unpaid" // PREVIOUS status of the transaction: unpaid ("unpaid")
            },
            "type": "charge", // type of charge that was changed (in this case, "charge" means that the change occurred in a transaction)
            "value": 6990 // value accompanying the change. This tag will exist when the change is a payment confirmation, informing the amount paid that was confirmed
        }
    ]
}


// All transactions have a status, which represents the situation of that transaction. Check out the full list for handling in your system

List of all possible statuses for transactions, installments, and subscriptions

All transactions, installments, and subscriptions have statuses that represent their "situations". Therefore, it is important to know the possible statuses in the API to provide the necessary handling in your system.


Order of notifications (callbacks)

In summary, the order of notifications always follows the sequence of events.

For example: in the case of installments, if installment 1 had its payment confirmed first, then installment 2, and finally installment 3. In this situation, we will have an array of 3 positions where the first presents the confirmation of installment 1, the second the confirmation of installment 2, and the last the confirmation of installment 3.

To know the most recent situation of the installment, you can traverse the array and check until which "event" was synchronized, as a notification can bring 2 or 3 updates, for example. Therefore, we cannot assume that the last position of the array is always the one that needs to be synchronized.


Explanation of response parameters:​

The response to a notification will always be an array containing the changes that occurred in a regular transaction, subscription, installment, subscription transaction, or installment transaction in the last 6 months.

Note that notifications related to subscriptions and installments may also include changes in their transactions (or installments).

Response tags
Here you will find a brief description of the attributes present in the notifications.



Notification Queue Status​

Efí notifies integrated systems of any changes in the status of a specific charge through its associated notification URL.

Notifications are processed and sent through a delivery queue. If the callback is rejected by the destination system, it automatically returns to the queue and is rescheduled for another delivery attempt. Callbacks are dynamic and can occur throughout the day.

To provide new ways to check the processing status of this queue, Efí offers a screen that allows you to check the consumption status of the processed notification queue. This way, if the client is unsure whether a callback has already been sent or not, they can monitor the daily processing of this queue.

To check the status and processing of the queue, please visit the Efí Payment Confirmations Status.

Videos: Notifications​

In an effort to provide new ways of conveying information, Efí offers the following video to explain, clearly and concisely, how to set up your notification URL to receive callbacks.

Setting up your notification URL (Efí API integration)​



Efí IP Addresses for Callback Delivery​

Some applications and services may filter our communications based on our IP addresses. Therefore, we recommend checking our list of IP addresses used by Efí. Check out our FAQ for the full list.

Next Steps​

Now that you've implemented the notification URL feature, you can learn more details on how to interpret relevant notification (callback) scenarios, such as situations where a charge in your system has not been downloaded, or when the callback was triggered for a URL you previously defined but is no longer valid, among other cases.


Understanding the Flow of Notifications​

This section aims to present the Notification History. This feature is available in your Efí account's API and allows you to view the POSTs that Efí sends to the integration partner's notification URL. These POSTs contain only a notification token.

By completing this reading, you will better understand the different scenarios related to notifications (callbacks). This includes situations where a charge in your system was not processed correctly, or when the callback was sent to a URL that you had previously defined but that URL is no longer valid, among other cases.

Understanding More About the Notification Flow​

Receiving a successful POST (status code 200) to your notification URL does not guarantee that the process has been completed correctly. After receiving the POST, it is important for you to come here and check the information.

IMPORTANT

The POST that Efí sends to your URL does not contain the billing information, only the notification token. All information about the billing in question will be provided when you access the endpoint GET /notification/:token.


In fact, the process works as a "two-way street". This means that Efí sends a POST to your notification URL whenever there is a change in the billing status. Then, your system, with the received notification token, makes a request to consume information through the endpoint GET /notification/:token, where ":token" is the notification token contained in the sent POST.

This way, we can consider that:

  • Sub-tab Notification History: indicates the POSTs that Efí sends to the registered notification URL.

  • Sub-tab Request History: upon successfully receiving the POST from Efí at your URL, your system will query the endpoint GET /notification/:token.

GET /v1/notification/:token
Returns the history of notifications sent for a given transaction.


Below is a simple JSON that can be used to return the history of notifications sent for a given transaction. You can also see the expected output. Remember that you also need to enter the "token" input parameter for the desired notification:

Input parameter: enter the token of the desired notification

Responses

The responses below represent consumption Success(200).

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "type": "carnet",
      "custom_id": "25452545",
      "status": {
        "current": "active",
        "previous": null
      },
      "identifiers": {
        "carnet_id": 8647
      },
      "created_at": "2016-06-28 13:28:21"
    },
    {
      "id": 2,
      "type": "carnet_charge",
      "custom_id": "25452545",
      "status": {
        "current": "canceled",
        "previous": "waiting"
      },
      "identifiers": {
        "carnet_id": 8647,
        "charge_id": 70712
      },
      "created_at": "2016-06-28 14:21:37"
    }
  ]
}

The flow is determined by the following order:

  1. Efí sends the POST containing the notification token to the registered notification URL whenever there is a change in the payment status. Details can be observed in the sub-tab Notification History;

  2. Your URL receives the POST, causing your system to send a GET request to the route /notification/:token, where :token is the notification token we sent to you. You can view this request in the sub-tab Request History.

IMPORTANT

If the integrator checks the sent token, we consider the notification successful. If not checked, we try again for up to 3 days.

In other words, if there is a request to the GET /notification/:token endpoint, we understand that you received the POST with the notification token and that you consulted it, receiving as a response all informative data about the change undergone by the payment, such as the previous and current status of the payment.

This information can be viewed in the sub-tab Request History, searching for the specific notification token.


Let's go through some examples:

Example 1: Notification with "Success (200)"​

Imagine a scenario where the integrator successfully receives the POST sent by Efí to its notification URL. Then, they consult our webservice to get the content of that notification token.

To analyze this:

  1. Access the sub-tab Notification History to see the received POSTs on your notification URL;
  2. With the notification token of the payment you want to check, access the sub-tab Request History.
  3. Search for the mentioned token, and upon finding it, click on the "eye" icon in the last column.
  4. This way, you can view all the information related to the payment that your system has consulted (read).
INFORMATION

In the sub-tab Notification History, the display of the response Success (200) only indicates that the POST was successfully sent to your notification URL, but it does not guarantee that your system was able to read and record the information on your side. To do this, you need to access the sub-tab Request History and locate the row containing the consumption of GET /notification/:token.


Summary of the steps followed:

  • Efí successfully sent a notification (POST) to your notification URL (check in the sub-tab Notification History);

    • This POST contains only the notification token, which is 7dd52fed-3d0a-42c8-b3fb-fc24f1d75303;

  • As soon as the URL received the notification, your system sent a GET request to the route /notification/7dd52fed-3d0a-42c8-b3fb-fc24f1d75303 (check in the sub-tab Request History);

    • At this point, your system received as a response a JSON with all informative data about the change occurred in the payment;

  • For this example, the entire flow was successful: we triggered the notification containing the notification token, and then your system queried our webservice to know (read) the information of the mentioned payment.


Example 2: Notification with "Failure (404)"​

Imagine a scenario where Efí sent the POST notification, but in the Notification History, the response displayed is Failure (404).

This Failure (404) indicates that the requested resource was not found. You should ensure that your URL is correct because we attempted to deliver the notification to the URL you provided us, but the address was not located.

Therefore, since your system failed to receive our callback, you will not see the consumption of GET /notification/:token in the Request History sub-tab.

Suggested Solutions:

  • You can adjust the URL path on your server side;

  • Update the notification URL to the new (and correct) address. To do this, you can send PUT requests to the appropriate API route, paying attention to the limit of up to 7,500 requests every 24 hours for this endpoint.

  • After updating the notification URL, we will continue to send the notification for the charge, but now to the new provided URL, as long as our first delivery was not more than 3 days ago. In this case, you can resend the API callbacks following the instructions in our FAQ.


Example 3: Notification with "Failure (301)" or "Failure (302)"​

Now, a scenario where Efí sent the POST (notification), but in Notification History the response is displayed as "Failure (301)" or "Failure (302)".

These situations occur when there is a permanent (301) or temporary (302) redirection on your server, specifically affecting the delivery of the notification to the notification URL you previously defined. Some common examples of when this occurs:

  • You set your notification URL as http://www.mywebsite.com, but later installed HTTPS/SSL on your server and your address became https://www.mywebsite.com;

  • Your notification URL was https://www.mywebsite.com, but later you created rules on your server (via htaccess, web.config, etc) and the address started responding only as https://mywebsite.com.

Suggested Solutions:

  • Adjust the 301 and/or 302 redirection rule on your server more accurately;

  • Update the notification URL to the new (and correct) address. To do this, you can send PUT requests to the appropriate API route, paying attention to the limit of up to 7,500 requests every 24 hours for this endpoint.

  • After updating the notification URL, we will continue to trigger the notification for the charge, but now to the new provided URL, as long as our first sending was not more than 3 days ago. In this case, you can resend the API callbacks following our FAQ guidelines.


Example 4: Notification with "Failure (500)"​

Finally, a scenario in which Efí sent the POST notification, but in the Notification History, the response is showing Failure (500).

Responses containing Failure (500) or 500 Internal Server Error are an HTTP error status indicating that the server encountered an unexpected condition that prevented it from fulfilling the request.

However, the error is a generic and broad message indicating a difficulty in processing on your server and can occur for various reasons.

Therefore, sometimes, your server's log files may respond with a 500 status code accompanied by more details about the request to prevent such errors from occurring in the future. Therefore, it is always extremely important that you check the error message from your server log to help you resolve it.

Below, we list the possible causes you can explore to solve the error:

  • Configuration file on your server, such as .htaccess, php.ini, or web.config, may contain invalid parameters;

  • Blocking on your server (network, firewall, policies, etc.): some applications and services may have certain filters, so make sure that our IP addresses are allowed.

  • High resource consumption on your server or process limit: shared hosts are more susceptible to this type of situation.

  • Timeout on your server.

  • Incorrect permissions on the server in files and/or folders.

  • Memory limit and PHP directives set in the php.ini file.

  • Conflict between PHP versions on your host.

  • Possibility of plugins, modules, extensions, or themes causing the error due to incompatibility or automatic updates.

Tip

As this is a generic error, it's important that you consult and interpret your server's error logs:

  1. Apache: /var/log/apache2/error.log
  2. NGINX: /var/log/nginx/error.log

If you don't have access to such information, please contact your hosting provider or your technical team responsible for the network infrastructure.


HTTP Status Codes (2xx, 3xx, 4xx, and 5xx)​

Efí uses HTTP responses to indicate success or failure in requests. Typically, you can view them through the Notifications History sub-tab.

Commonly, when we return responses with a 2xx status, it means the request was successful; 3xx statuses indicate redirection; 4xx statuses indicate client-side data transmission failures; 5xx statuses indicate internal server errors.

HTTP status codes
Description of the most common HTTP codes and their explanations and solutions:


NOTE

If you encounter any response code different from those mentioned above, we recommend accessing the list of HTTP status codes on Wikipedia and checking it out.


Confirmation Files​

With the aim of further diversifying its solutions, Efí has adopted Electronic File Exchange to provide information regarding charges for customers who cannot (or do not wish to) use automatic notifications between systems (callbacks via notification URL).

The Confirmation File contains all confirmed payments from your Efí account, meaning all transactions with the status paid. The file includes transactions made through integration (API) and/or the Efí platform.

IMPORTANT:

Manually confirmed transactions (status settled) will not be included in this file.


Before proceeding, it is important to be aware that this page is of a technical nature. This documentation provides technical guidance on how to use the Confirmation Files of Charges and establishes the basic conditions for their use.

Download the Confirmation File​

You can download the file and import it into your system to reconcile the paid boletos. To generate the file, follow the instructions below:

  • Log in to your Efí account and go to Receive (Charges) > Automations > Confirmation Files;

  • Select a specific date to generate a file containing the confirmations that occurred on that day;

  • The file will be generated. Download and import it into your system.

NOTE

Make sure your system is ready to import and interpret the Confirmation File layout.


Below is the layout with the presentation of fields, description, start and end positions, type, size, and other information:
banner

Layout Efí Return File


Example of Confirmation File Return:​

banner

Example Confirmation File


Requests​

Callback requests expect a response with HTTP status 2XX. If the client's server returns a different status, Efí will make up to 10 new notification attempts. The first new attempt will be made 5 minutes after the callback delivery failure. If the error persists, subsequent attempts will be sent at increasingly longer intervals, as shown in the table below.

Important!

In cases where the client's server returns HTTP status 429 (too many requests), Efí's servers will also attempt to send the notification up to 10 times according to the table below.


N° of attemptsTime (in minutes)
15
210
320
440
580
6160
7320
8640
91280
1052560
Last updated on