Pre-authorization status query service
In case of communication failure or excessive timeout in any of the operations subsequent to beginTransaction, the store must make use of getStatus. This operation allows you to check the status of a request to which the merchant did not receive the response, retrieving the parameters that could not receive in the normal flow.
The store must retrieve the transaction status (within a 15 days limit) as long as it has the nit, through webservice getStatus, passing as the store authentication key (merchantKey) and the nit.
Development/Certification teams: If you haven't received the merchantKey, please request by e-mail authorizers5317@softwareexpress.com.br or by phone +55 11 3170-5317.
Production teams: merchantKey will be sent by the Carat Portal Production team, if you have not received it after the proper procedures to start Production, please email esitef.prod6773@softwareexpress .com.
Note that in exceptional cases the authentication key (merchantKey) may be changed for security reasons, but the production team will contact the store prior to the change.
Recalling that several factors can cause the delay in response, including internet instability and the authorizers network. We recommend that the store server has a timeout of 90 seconds or more.
Note: This service will only return data if the transaction is done via Web Services, it will not work for transactions via HTML Interface.
Warning: The transaction query in Carat Portal DOES NOT query the transaction status of the acquirer/authorizer. This service returns the transaction status in the Carat Portal database.
Example: If a pre-authorization transaction is confirmed on Carat Portal but charged back via telephone directly with the acquirer/authorizer, this chargeback will not necessarily be reflected in the Carat Portal transaction inquiry service.
Call details#
- Resource:
/v1/transactions/{nit} - HTTP Method:
GET - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
Content-Type | Fixed value "application/json" | = 15 A | Yes |
merchant_id | Carat Portal store's ID. Production and certification IDs are different. | ||
merchant_key | Store authentication key in Carat Portal. Production and certification keys are different. | ≤ 80 A | Yes |
nit | Pre-authorization transaction ID in Carat Portal. Obtained at beginTransaction response. | = 64 A | Yes |
Request Parameter#
Parameter nit should be sent on the resource URL
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
nit | Pre-authorization transaction ID in Carat Portal. Obtained at beginTransaction response. | = 64 A | Yes |
Transaction query operation call - getStatus - does not require request body.
Response Parameter#
| Parameter | Description | Format |
|---|---|---|
code | Carat Portal response code. Any code other than zero means failure. For more information, see Responde Codes. | < 4 N |
message | Carat Portal's response message. | < 500 AN |
acquirer_id | Acquirer/Routing ID used in transaction. | < 4 N |
acquirer_name | Acquirer/Routing name used in transaction. | < 100 AN |
amount | Transaction's amount defined by the store (in cents) at transaction creation. | < 12 AN |
authorization_number | Authorization Number. | < 6 AN |
authorizer_code | Authorizer code | < 10 AN |
authorizer_date | Authorizer pre-auth effectuation date, returned by the authorizer on the format DD/MM/AAAA’T’HH:mm. Example: 13/07/2017T16:03 | = 16 D |
authorizer_id | Authorizer ID use in transaction. | < 4 N |
authorizer_merchant_id | Merchant ID from authorizer. | < 100 AN |
authorizer_message | Reponse message from authorizer. | < 500 AN |
customer_receipt | Customer receipt. | < 4000 AN |
eci | Eletronic Commerce Indicator (pre-authorization security level indicator on transactions via Cielo e-Commerce). | < 3 AN |
esitef_usn | Carat Portal pre-authorization's unique sequential number. | = 15 N |
host_usn | Authorizer NSU. | < 15 AN |
issuer | Issuer code returned by the authorizer. | < 5 AN |
merchant_receipt | Merchant receipt. | < 4000 AN |
merchant_usn | Unique sequential number sent by store at the transaction creation. | < 12 AN |
nit | Carat Portal pre-authorization transaction ID. | = 64 AN |
order_id | Order ID sent by the store at transaction creation. | < 40 AN |
payment_type | Payment type from the selected authorizer: B = boleto, C = credit, D = debit, P = Private Label credit card, T = bank transfer, G = gift card, O = other ways of payments, W = Boleto NR via Web Service | = 1 A |
sitef_usn | SiTef pre-authorization's unique sequential number. | = 6 N |
status | Carat Portal pre-authorization transaction status. | = 3 AN |
tid | Acquirer/routing transaction ID. This field is only returned in transactions with external acquirer's. | < 40 AN |
xid | XID field returned on 3DS authentications or certain acquirers/routings. | < 40 AN |
| pre_authorization.analysis | ||
code | Response code of the fraud analysis operation on pre-authorization. | < 4 N |
message | Response message of the fraud analysis operation on pre-authorization. | < 200 AN |
status | Status of the fraud analysis transaction on pre-authorization. This field can assume the following value:NOV – New.EXP – Expired.ACC – AcceptedREJ – RejectedREV – In reviewINV – Invalid | = 3 AN |
Warning: Fields
codeandmessagerefer to query request code and message. They do not refer to to the queried transactions.
Example#
Request:
To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br
Response:
Response codes
See reference on API codes - response codes
Querying transactions from a group of merchants#
Carat Portal requires that the credentials (merchant_id and merchant_key) are the same used on the transaction to be queried. However, if the merchant needs, Carat Portal can allow queries with credentials from other merchants from the same group. For that, just request our support and production teams to make this configuration.