REST Pre-authorization

Overview

Pre-authorization (pre-auth) is a transaction whose funds will be put on hold from the card limit, but will not be debited immediately and can be captured later for an amount equal or less than the authorized. The duration of the hold, as well as the possibility of capturing smaller amounts will depend on the negotiation with the network acquirer/routing, the virtual store will consult the network acquirer/routing.

Pre-authorization is used whenever is necessary to capture the transaction after a long period of time. Thus, you can only authorize a payment transaction and confirm/capture it on a later day. The difference between a later confirmed payment and a pre-authorization with capture is the deadline in which the transaction can be completed.

The time allowed to confirm/capture a pre-authorization is longer than a payment with subsequent confirmation. For better understanding, we can cite the following application examples:

A car rental company issues a payment request to a customer. The company will capture/confirm the transaction only when the customer returns the car, which may take a few days. In this scenario, it would be recommended to use a Pre-Authorization transaction .

A store issues a payment request, but before confirming/capturing the transaction, it checks the stock to check the availability of a payment method, which could take a few minutes or hours, and then effect the payment. In this scenario, it would be recommended to use a common payment transaction with later confirmation.

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 e minimum protocol TLS 1.2. 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/

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.

Flow

The pre-authorization flow will be started by the virtual store when the application submits the beginTransaction operation, in the request response the application will receive nit and other parameters.

Flow description:

1. When starting the beginTransaction operation through the virtual store, a nit (transaction id) and other parameters are returned;
2. The virtual store then proceeds to consume the doPreAuthorization, pre-auth effectuation operation, passing the nit and the other parameters received. If successful, the pre-authorization transaction will change its status to CON (confirmed transaction).
3. Subsequently (according to the business rule) the same nit sent in the pre-authorization should be sent in the capture operation along with other parameters and should handle the parameters received in the webservice response.