Itaú Shopline
Carat Portal allows integrating the merchant' site with payments through Itaú Shopline, where the buyer access his own account through Itaú interface to make the payment via boleto bancário, bank transfer or using Itaucard cards.
In this page, the nomenclature "Itaú Shopline" will be used to reference the acquirer on Carat Portal.
Carat Portal Interfaces Supported for Integration#
The following interfaces for integration with Itaú Shopline are available:
- HTML Payment
- Reissue of boletos
Allowed Authorizers / Issuers#
The following authorizers / issuers are available for integration with Itaú Shopline:
- Itaú Shopline
Required credentials#
The merchant must obtain with Itaú the credentials listed below, and pass them to Software Express.
| Field | Field description | Format |
|---|---|---|
codigoEmpresa | Company code (merchant) on Itaú. | = 26 AN |
chave | Cryptography key for information exchange with Itaú Shopline. | = 16 AN |
Itaú Shopline Portal required configurations#
Some configurations must be done on the merchant's account on Itaú Shopline for flawless integration with Carat Portal.
Return URL#
For a correct operation of the payment confirmation, it is required the merchant logs on Itaú Bankline with his credentials and configure Shopline's Return URL field with the Carat Portal URL below:
| Production environment |
|---|
| https://esitef-ec.softwareexpress.com.br/e-sitef/itau.se |
| UAT environment |
| https:///itau.se |
This URL is used for Itaú to confirm the payment on Carat Portal. There is a 60 characters limitation on Itaú Shopline for the URL, so be very careful when registering the URL, as it's different depending on the environment (UAT or Production).
Notice that updates on Itaú can take one business day to become available.
Below is a copy of the Itaú Shopline technical manual for accessing account data.
(Retrieved from Itaú Shopline technical manual)
On Itaú Bankline, the path to access this function is: Products and Services > Itaú Shopline > Account Data
(...)
Attention: Any information updated in this environment will be available for usage 1 (one)business day after the update. To access Itaú Bankline, it is required to go to Itaú site (http://www.itau.com.br/) and type:
- Agency data, Current Account and Electronic Password on Itaú Bankline Enterprise access bar;
- or Operator User data and Electronic Password on Itaú Bankline Enterprise Plus access bar.
Payment Flow with Itaú Shopline#
After configuring this payment method for the merchant, the payment flow occurs the following way:
- User starts a payment via Carat Portal.
- The list of authorizers configured for the merchant is presented to the user.
- User selects Itaú Shopline payment method.
- At this moment a new window will open redirecting the user to Itaú Shopline.
- User starts the payment process on Itaú Shopline's website.
- User finishes the payment on Itaú Shopline's environment.
- Itaú Shopline redirects user to Carat Portal, according to the configured return URL.
- Upon receiving the user redirect, Carat Portal makes a query to Itaú and updates the transaction status.
- If the merchant has configured auto redirection, user is redirected to the Success or Failure URL configured on Carat Portal.
- In the end, if there is auto redirection, the user returns to the merchant website.
In the image below we can see in the diagram the flow described above:
An exception case to that flow is the case in which the Return URL was not registered on Itaú. Therefore, there will not be user redirection after the payment is finalized on Itaú Shopline.
Another possible case is starting a transaction with a pre-fixed authorizer, in which steps 2 and 3 are not necessary.
Thus, we suggest the configuration described in Return URL is made correctly, to allow a better shopping experience to the user.
Status Notification#
For each transaction status update on Carat Portal, resulting from communication between Carat Portal and Itaú, it is sent to the merchant server a Status Notification. For further details about that functionality, see the HTML Payment in Status Notification.
Parameters for transaction via Itaú Shopline#
The parameters used to create a payment transaction with Itaú Shopline are the same presented in HTML Payment on item Initializing a payment transaction.
Order Id
To use the Itaú Shopline payment method, it is required that the order id is always different for every transaction, and has eight digits only. This order id cannot repeat for 60 days (according to information from Itaú on 12/2010), and must be numeric. If the merchant submits more than eight or containing alphanumeric characters, Carat Portal will:
- Remove all non-numeric characters.
- Keep the last eight remaining digits (to the right).
- Submit “0” if nothing remains.
Important: Carat Portal will not verify if the ids are repeating, and Itaú Shopline could even accept repeated order ids, however errors might happen, like non-paid new orders return as confirmed by Itaú. Carat Portal does not take responsibility for repeated order ids.
Itaú Shopline Payments via Boleto Bancário
In case the user selects Itaú Shopline payment via boleto bancário, the payment confirmation can take up to one business day to happen on Itaú, and keep itself in Pending status on Carat Portal during that period.
As Itaú does not inform Carat Portal when the payment of the boleto was done, Carat Portal can take more than one day to confirm, as the probe that updates the status of the boleto payments is executed just at dawn. In that case, the redirection to the success URL by Carat Portal, for the boleto selection case, will happen by the moment Itaú generates the boleto. It is up to the merchant to verify the transaction final status on Carat Portal.
If it is verified that the boleto date is beyond the days configured for cancellation, then the transaction status will be changed to Expired, so that the boleto payment status queries on Itaú are finished. If a payment transaction with Expired status on Carat Portal is made on Itaú environment, once Itaú notifies Carat Portal that the payment was done successfully, the transaction will be resumed and the payment will be made normally; if the payment is made with success, the transaction status is changed from Expired to Confirmed.
Pay attention to the fact that, for each transaction status update on Carat Portal, a POST will be submitted to the merchant's Status Notification URL registered on Carat Portal.
So that the customer can make a boleto bancário payment, it's necessary that the store submits to Carat Portal the following information:
| Field | Description | Format | Mandatory |
|---|---|---|---|
identification_number | Customer identification number (CPF or CNPJ) If the customer identification number is greater than 11 digits the field will be considered CNPJ. | < 20 N | YES |
|name
For Itaú Shopline, name and surname plus a white space between them must have, at most, 200 alphanumeric characters.
surname|
|address_street_nameFor Itaú Shopline, the street name, number and complement of the address plus the white spaces between them must have, at most, 200 alphanumeric characters.
address_street_number|
|address_street_complement|
|address_zip_code|Customer ZIP|= 8 N|YES|
|city|Customer city|< 100 AN|YES|
|state|Customer state|= 2 AN|YES|
|neighborhood|Customer neighborhood|< 15 AN|YES|Below is a usage example on Carat Portal's HTML Interface, with the request JSON object sent on the POST:
Reissue of boletos#
It is possible to make available to customers the reissue of Itaú Shopline boletos.
That functionality is available through the URL:
| Production environment |
|---|
| https://esitef-ec.softwareexpress.com.br/e-sitef/reissue.se?nit=XXX |
| UAT environment |
| https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/reissue.se?nit=XXX |
You must inform as a POST parameter the nit used in the original payment transaction, made via Itaú Shopline. The access itself to that URL already allows a direct visualization of the reissued boleto with the same data of the first emission.
If the payment transaction is not in the expected state, it is present an error message.
Attention
The IP address must never be used instead of the domain esitef-ec.softwareexpress.com.br (or esitef-homologacao.softwareexpress.com.br for Certification and Test environment). The IP address can change at any moment without notice, so it is important to always use the domain to access Carat Portal.