REST Schedule

Overview

Carat Portal has two interfaces for integration with the virtual store, HTTPS POST and HTTPS Web Services, enabling the proper way of interaction between the merchant and Carat Portal, according to the programming language and the platform of the virtual store.

On the REST Web Service interface, the payment and card data will be collected by the merchant and Carat Portal will only make the payment with the financial institution.

This interface provides payments with credit, debit or voucher cards. For payments such as electronic transfer or boleto, the POST/HTML interface must be used instead.

Also available on this interface is the recurrent payments scheduling functionality.

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' server supports encryption of a minimum of 128 bits. The merchant' 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.softwareexpress.com.br/e-sitef/api

Homologation base URL:

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

Every call received by the services will be responded synchronously.

Attention:

Never use the IP instead of the esitef-homologacao.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.

Flow

It's possible to schedule recurrent transactions with or without an immediate payment. In the case of schedule with payment, Carat Portal assures the atomicity of the operation, which means that the schedule will only be activated if the payment is confirmed.

Schedule with immediate payment

Flow description:

1. The merchant creates a transaction on Carat Portal passing the payment and schedule data and obtains as response a NIT (Transaction Identifier Number). The simple fact that schedule data were sent will be interpreted as payment with schedule.
2. The merchant then proceeds consuming the payment effectuation service, passing the NIT and the customer's card data. In case of success, the payment transaction will change its status to CON (confirmed) and the schedule transaction will assume the status ATV (active).

It's also possible to make a payment with schedule with late confirmation. The flow to be followed is the same as in a simple payment with late confirmation. Learn more.

Schedule without immediate payment

Flow description:

1. The merchant creates a transaction on Carat Portal passing the schedule data and the do_payment_now parameter with the value false. As a response, the merchant will obtain a SID (schedule identifier).
2. The merchant then proceeds consuming the schedule activation service, passing the SID and the customer's card data. In case of success, the schedule will have its status changed to ATV (active).

Schedule query

The information of the schedule transactions can be queried through the same service used on the REST Payment interface. Learn more.