Transaction query service
The merchant's application must perform a status query when some issue occurs with the transaction status receiving.
Flow#
To perform the query, the merchant must make a POST in the following address:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/consultarTransacao.se?nit=XXXXX
Where "XXXXX" is the NIT sent by Carat Portal on the transaction creation. The response will be "OK" if the NIT is correct and the communication ended properly.
After this, Carat Portal will send a POST/HTTPS to the status notification URL registered on Carat Portal, sending as parameter the status code of the transaction. The merchant must be prepared to handle these statuses and the HTTPS (SSL/TLS) calls to the registered status notification URL.
Carat Portal's POST/HTTPS may not be immediate, as it will be asynchronous. The delay may vary according to the server load and the internet. If a problem occurs on sending, Carat Portal will try to resend the message after a certain time range, up to 3 times.
The merchant must accept the POST/HTTPS via SSL/TLS with a valid certificate. But still, importing the certificate on Carat Portal may be necessary.
Another relevant point is that Carat Portal always awaits a 200 ("OK") response from the status notification URL, and doesn't accept a redirection (302) to another URL or another web site.
Note:
The Carat Portal transaction status query service DO NOT makes a transaction status check in acquirer / authorizer. This service only returns the transaction status in Carat Portal database.
Example: If a payment transaction is confirmed in Carat Portal, but is reversed via telephone directly to the acquirer / authorizer, this reversal will not necessarily be reflected in the Carat Portal transaction status query service.
When to use the status query?#
If somehow the merchant application exceeds the timeout and does not receive the status notification from Carat Portal due to some infrastructure problem or some issue with the server that has blocked the receiving of the response, the merchant's application must perform a Status Query. In this query, the merchant's application receives all the transaction parameters that it should have received if the status notification had worked properly. Thus, the merchant can avoid sending the same payment twice.
It is extremely important that the merchant application knows the transaction status on Carat Portal before performing any other transaction handling, so that it's possible to prevent that the customer performs a new attempt of payment of a same order, without knowing the result of the payment requested previously.
Example:
If the registered merchant status notification URL is:
https://www.storetest.com.br/status.php
The merchant will receive a POST on:
https://www.storetest.com.br/status.php
With the parameters:
Status notification POST
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Status notification POST parameters#
The table below describes the parameters sent by Carat Portal on the Status notification POST:
| Parameter | Description | Format |
|---|---|---|
nsuSitef | Transaction number at Sitef | = 6 AN |
nit | Carat Portal transaction ID. | = 64 AN |
pedido | Order ID of the payment created by merchant | < 20 AN |
status | Transaction status on Carat | = 3 N |
Carat Portal can also send new parameters without previous warning, which means that the merchant’s application must be prepared to receive extra fields and just ignore them.
Note:
Do not overuse the Transaction query status function. If overuses are identified, Carat Portal can ignore future calls.