REST Recharge

Overview

The data collection will be conducted by the store, which will capture top up and card data (in case of top up with payment) or only top up data (if it's desired to perform only a top up).

And to learn more about these nomenclatures (Bin, Software Express, Carat, e-Sitef) Learn more

Communication

To make a Web Service transaction, the whole communication must be done via HTTPS/TLS. It's important that the merchant's server supports encryption of a minimum of 128 bits. The merchant's server must make calls on specific addresses to do REST transactions.

Each service must be called using the base URL concatenated with the desired resource (see the chapter related to the service to be consumed). The HTTP method (GET, POST or PUT) indicates the expected action on the selected resource. Listed below are the base URLs of Carat Portal:

Production base URL:

https://esitef-ec.softwareexpress.com.br/e-sitef

Homologation base URL:

https://esitef-homologacao.softwareexpress.com.br/e-sitef

Every call received by the services will be responded synchronously.

Attention:

Never use the IP instead of the esitef-ec.softwareexpress.com.br domain. The IP can change at any time without previous warning, so it's important to use the domain when accessing Carat Portal.

Important:

Besides the response parameters of the services described in this specification, Carat Portal can return other parameters without previous warning.

It's important that the application is prepared to receive the unknown parameters besides the fields already specified and simply ignore them.

Recharge flow without payment

The recharge flow without payment can be performed as shown in the figure above.

The developer must follow what was specified in the Carat Portal integration document and send the parameters:

• According to the size and type (numeric or alphanumeric);
• Whether the field is mandatory, conditional or optional.

Briefly, below is the transactional flow for Recharge. With this, some doubts should be clarified, streamlining the integration process with Carat Portal.

• 1. The flow starts with the application of the store making a call to create the recharge transaction;
  • 1.1. Synchronously, Carat Portal will do a HTTPS POST on the authenticity URL informed by the merchant and registered on the Carat Portal backoffice. The POST sent will contain the NIT needed to proceed with the recharge;
  • 1.2. The response of the store to the HTTPS POST must be "200 OK";
  • 1.3. The Carat Portal response to the begin recharge call will be a code indicating success (value 0) or failure (any value other than 0);
• 2. The store must then make a call to list dealers passing the previously received NIT;
  • 2.1. Carat Portal returns a list containing the data of the dealers;
• 3. The store must then make a call to list branch data by passing the chosen dealer code, the desired area code (DDD), and the NIT;
  • 3.1. Carat Portal returns the branch data, including possible recharge amounts, expiration periods, bonus amounts, among others;
• 4. The store must then make a call to perform recharge passing the NIT, the chosen dealer code, the phone number, the area code (DDD) and the selected value;
  • 4.1. Carat Portal performs the recharge with the chosen dealer and returns the data of the recharge pending confirmation;
• 5. The store must always make a call to confirm the recharge passing the NIT and a field indicating if the pending recharge must be confirmed or undone on the dealer;
  • 5.1. Carat Portal returns a response indicating the result of the confirmation or undoing of the recharge;

Recharge flow with payment

The recharge flow with or without payment is the same, with the addition that the payment flow requires that the payment data is sent on the recharge call.