Query
This service can be called to obtain data from the payment or refund. In the case of payment with schedule, the queries will return the data from both transactions.
Note:
The Carat Portal transaction 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 directly to the acquirer / authorizer, this reversal will not necessarily be reflected in the Carat Portal transaction query service.
Query by NIT#
Call details#
- Resource:
/v2/transactions/{nit} - HTTP Method:
GET - Request format:
there are no request parameters - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Examples#
Payment query#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response in case of request found:
Response in case of request not found:
Refund query#
When requesting the refund service a new transaction will be created with a different NIT from the original payment transaction. If successful the payment transaction will have its status changed to EST (reversed) and the refund transaction will have CON status (confirmed). Each of these operations can be queried by their respective NITs.
Payment transaction NIT
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Response in case of request not found:
Refund transaction NIT
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Response in case of request not found:
Query by order_id#
Call details#
- Resource:
/v2/transactions?order_id={order_id} - HTTP Method:
GET - Request format:
query string - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Examples#
Payment query#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response in case of request found:
Response in case of request not found:
Refund query#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Response in case of request not found:
Response parameters#
In case of success, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes de response parameters of the transaction creation service:
| Parameter | Description | Format |
|---|---|---|
code | Carat Portal response code. Any code different from 0 means failure. Learn more. | < 4 N |
message | Carat Portal response message. | ≥ 500 AN |
current_page | Current records page. | < 4 N |
total_pages | Total pages number. | < 4 N |
count | Total register count. | < 4 |
| payment | ||
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
nit | Payment transaction identifier on Carat. | = 64 AN |
order_id | Order code sent by the merchant on the creation of the transaction. | < 40 AN |
merchant_usn | Unique sequential number sent by the merchant on the creation of the transaction. | < 12 N |
amount | Total price of the purchase specified by the merchant (in cents) on the creation of the transaction. | < 12 N |
sitef_usn | Unique sequential number of the payment transaction on SiTef. | = 6 N |
esitef_usn | Unique sequential number of the payment transaction on Carat Portal. | = 15 N |
customer_receipt | Customer's receipt. | < 4000 AN |
merchant_receipt | Merchant's receipt. | < 4000 AN |
authorizer_id | Code of the authorizer used on the transaction. | < 4 N |
acquirer_id | Code of the acquirer used on the transaction. | < 4 N |
acquirer_name | Name of the acquirer used on the transaction. | < 100 AN |
authorizer_date | Payment authorization date returned by the authorizer in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |
authorization_number | Authorization number. | < 6 AN |
host_usn | Host USN. | < 15 AN |
tid | ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef. | < 40 AN |
eci | Eletronic Commerce Indicator (security level indicator of the payment transaction). | < 3 AN |
payment_date | Payment authorization date on Carat Portal in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |
issuer | Issuer code returned by the authorizer. | < 5 AN |
authorizer_merchant_id | Affiliation code of the merchant on the authorizer. | < 100 AN |
terminal_id | Terminal code used in the transaction | < 8 AN |
authorizer_code | Authorizer response code. | < 10 AN |
authorizer_message | Authorizer response message. | < 500 AN |
installments | Number of installments to be used on the scheduled payments. | < 2 N |
is_host_cancel | This field will return the value true in case of refund via host. | < 5 T/F |
customer_receipt | Customer's receipt. | < 4000 AN |
merchant_receipt | Merchant's receipt. | < 4000 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 payment methods, W = Boleto NR via Web Service | = 1 AN |
| cancellation | ||
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
order_id | Order code sent by the merchant on the creation of the transaction. | < 40 AN |
merchant_usn | Unique sequential number sent by the merchant on the creation of the transaction. | < 12 N |
amount | Total price of the purchase specified by the merchant (in cents) on the creation of the transaction. | < 12 N |
sitef_usn | Unique sequential number of the payment transaction on SiTef. | = 6 N |
esitef_usn | Unique sequential number of the payment transaction on Carat Portal. | = 15 N |
customer_receipt | Customer's receipt. | < 4000 AN |
merchant_receipt | Merchant's receipt. | < 4000 AN |
authorizer_id | Code of the authorizer used on the transaction. | < 4 N |
acquirer_id | Code of the acquirer used on the transaction. | < 4 N |
acquirer_name | Name of the acquirer used on the transaction. | < 100 AN |
authorizer_date | Payment authorization date returned by the authorizer in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |
authorization_number | Authorization number. | < 6 AN |
host_usn | Host USN. | < 15 AN |
tid | ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef. | < 40 AN |
eci | Eletronic Commerce Indicator (security level indicator of the payment transaction). | < 3 AN |
payment_date | Payment authorization date on Carat Portal in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |
issuer | Issuer code returned by the authorizer. | < 5 AN |
authorizer_merchant_id | Affiliation code of the merchant on the authorizer. | < 100 AN |
terminal_id | Terminal code used in the transaction | < 8 AN |
authorizer_code | Authorizer response code. | < 10 AN |
authorizer_message | Authorizer response message. | < 500 AN |
installments | Number of installments to be used on the scheduled payments. | < 2 N |
is_host_cancel | This field will return the value true in case of cancel via host. | < 5 T/F |
esitef_date | Refund authorization date on Carat Portal in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |
customer_receipt | Customer's receipt. | < 4000 AN |
merchant_receipt | Merchant's receipt. | < 4000 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 payment methods, W = Boleto NR via Web Service | = 1 AN |