Receiving notifications

Notifications allow you to be informed when a transaction (also called a "charge") has changed status. This way, you will be able to identify when a charge is paid, for example.

When a transaction has a notification URL registered (attribute notification_url), Gerencianet triggers a POST to this URL every time the charge status changes. This notification has a specific token, which will be the same throughout the entire "change cycle" of the transaction. For example:

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

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

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

A POST will contain only one piece of information: a notification token. That is, if the registered URL is prepared to read the token in the variable $_POST['notification'] and consult this information, the answer will be all informational data about the change suffered by the charge, such as, for example, the previous and current status of the charge. To do so, you need to register a notification URL in the charge and prepare it to show/store the notification token.

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

Any time the integrator consults this notification token, it will obtain the most current charge information, all sorted according to events. Every change in status generates a notification.

On the tab Notification History it is possible to track every notification POST triggered by our system. If the integrator queries the sent token, we consider that the notification was successful. If not, try again.

To view the table containing all the status of a transaction, booklet or subscription, access this link in our documentation.

The rest of this page has the detailed procedures, but you need to install one of our libraries on your server to run the sample code. Make sure the Gerencianet SDK has been installed.



1. Setting the URL for receiving notifications

PTo proceed with the execution of the following codes, make sure that the Gerencianet SDK has been installed. You will be able to define a URL that will receive notifications during the creation of the charge (createCharge) or later (updateChargeMetadata).

A transaction generated through the API may undergo several status changes depending on the interactions of the payer, the integrator or the operators and banking institutions involved. To keep up with these changes, it is necessary to prepare your system to receive notifications sent by Gerencianet.

When defining the parameters for creating the transaction, you can set a notification url. This URL will receive a token when a transaction has a status change. With this token, your application will be able to query our webservice to obtain the transaction status.

$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 Gerencianet($options);
$charge = $api->createCharge([], $body);
}

Dica para testar as notificações (callbacks) facilmente com o WebhookInbox

To test notifications, we suggest using the WebhookInbox, which is a free service to inspect HTTP requests. You will be able to create a temporary URL to use it in the attribute notification_url, in order to visualize, in an easy and friendly way, the POSTs made for your application. To generate the URL that will receive the request, access WebhookInbox and click Create An Inbox.

WebhookInbox will record HTTP requests and allow you to inspect them to check Headers and Body of the requests. In this way, you will be able to start developing your integration with Gerencianet and test the Notification URL (callbacks) even if you don't already have a public URL available.


If you do not register a URL at the time of creating the transaction, you can do so through the metadata change method, through a PUT request for the route /v1/charge/:id /metadata.

You should note that the notification process is carried out in two steps to ensure the security of the reported data:

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

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


2. Consult notification details

Gerencianet considers that a notification was successful only after this consult. As long as your system does not consult the notification details, it will continue to be notified:

<?php
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id';
$clientSecret = 'informe_seu_client_secret';
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true
];
/*
* This token will be received in your variable that represents the POST parameters
* Ex.: $_POST['notification']
*/
$token = $_POST["notification"];
$params = [
'token' => $token
];
try {
$api = new Gerencianet($options);
$chargeNotification = $api->getNotification($params, []);
// To identify the current status of your transaction you must count the number of situations contained in the array, as the last position always holds the last status. See the sample responses in the "Example Responses" section below.
// See below how to access the ID and String referring to the last transaction status.
// Counts the size of the data array (which stores the result)
$i = count($chargeNotification["data"]);
// Get the last Object chargeStatus
$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 will be able to consult 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 (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

2.1. Exemplos de respostas:

A seguir alguns exemplos de respostas de notificações para transações, assinaturas, carnês e link de pagamento:

{
"code": 200, // HTTP return "200" informing that the request was successful
"data": [
{
"created_at": "2022-02-20 09:12:23", // date of array status change "id 1"
"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 have 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 array status change "id 2"
"custom_id": null, // charge identifier defined by the integrator, if exist
"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 array status change "id 3"
"custom_id": null, // charge identifier 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 array status change "id 4"
"custom_id": null, // charge identifier defined by the integrator, if any
"id": 4,
"identifiers": { // identifiers representing the charge
"charge_id": 24342333
},
"received_by_bank_at": "2022-04-02", // charge payment date
"status": {
"current": "paid", // CURRENT transaction status: paid ("paid")
"previous": "unpaid" // PREVIOUS transaction status: 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 status, which represents the status of that transaction. Check the complete list for dealings in your system


List of all possible transaction, carnets and subscriptions statuses

All transactions, booklets and signatures have status, which represents their "situations". Therefore, it is important to know the possible statuses in the API to provide the proper handling in your system.

Check this link for all the details of the possible statuses.



Order of notifications (callbacks)

In short, the order of notifications is always the order of events.

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

To find out about the most recent situation of the parcel, you can scan the array and know (store) until which "event" was synchronized, as it may be that a notification brings 2 or 3 updates, for example, so you can't consider that the last position of the array is always the one that needs to be synchronized.



2.2. Explanation of response parameters:

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

Note that notifications related to subscription and booklet may also be accompanied by changes in your transactions (or installments).


2.3. Response tags:

TagDescription
idOrder indicator, started on 1. It is incremented for each change of a notification token. This is useful if you need to keep track of which change you have already processed.
typeDetermines the type of charge that was changed.

Possible types are:
charge // The change occurred in a transaction.

subscription // The change occurred in a subscription.

carnet // The change took place in a carnet.

subscription_charge// The change occurred in a subscription installment.

carnet_charge // The change occurred in a parcel of the carnet
custom_idInforms the charge identifier defined by the integrator, if any.
statusDefines the current and previous status of the transaction, subscription or carnet.

Status attributes:
current

previous

Note: if there is no previous state (that is, for new charges), the previous value will be null
identifiersIdentifiers representing the charge. The attributes of this tag may vary depending on the type of change (parameter type).

Identifiers that can be returned:
charge_id // Returned when type = "charge"

subscription_id // Returned when type = "subscription".

carnet_id // returned when type = "subscription".

charge_id and subscription_id // returned when
type = "subscription_charge".

charge_id e carnet_id // returned when type = "carnet_charge".
valueValue accompanying the change. This tag will exist when the change is a payment confirmation, informing the amount paid that was confirmed.
**Fields with * represent mandatory values**

3. Notification queue status (callback)

Gerencianet notifies the integrated systems of each change in the status of a given charge through its associated notification URL.

Notifications are processed and always sent through a submission queue. It is also worth remembering that, if the callback is rejected by the destination system, it automatically returns to the queue and is rescheduled for a new delivery attempt. Callbacks are dynamic and can occur throughout the day.

Thinking about offering new ways of consulting the processing of this queue, Gestoret provides a screen that allows consulting the consumption status of the notifications queue (callbacks) processed until then. In this way, if the customer is in doubt as to whether a callback has already been sent or not, he can follow the daily processing of this queue.

To see the status and processing of the queue, see the link status of payment confirmations - Gerencianet.

4. Videos: Notifications

Thinking about offering new means of transmitting information, Gerencianet makes the following videos available in order to explain, in a clear and objective way, how to implement and configure your notification URL to receive callbacks.


4.1. Implementing Notifications - Callback or Auto Return (via Playground)



4.2. Configuring your notifications URL (Integration Gerencianet API)






5. IP addresses of Gerencianet for delivery of callbacks

Some applications and services may filter our communications through our IP addresses. Therefore, we recommend checking through the list of addresses used by the Gerencianet. Check it out in full in our FAQ.


6. Complementary Information: status of transactions, carnets and subscriptions

check out this link the table containing the possible status of a transaction, carnets and subscriptions in Gerencianet API.


7. Next steps

Now that you've implemented the Notification URL feature, you can check out more details this link on how to interpret scenarios pertaining to notifications (callbacks), such as in situations where a charge on your system has not been downloaded, the callback has been triggered to a URL you previously defined but which is no longer valid, etc.