Recharge query service
This call allows the store to query the status of a recharge and its related payment (if any) on Carat Portal, at any time within the flow, after creating a recharge.
Attention:
The transaction status query on Carat Portal does NOT query the status of the transaction on the acquirer / authorizer. This service returns the transaction status on the Carat Portal database.
Example: If a payment transaction is confirmed on Carat Portal, but is reversed via telephone directly to the acquirer / authorizer, this reversal will not necessarily be reflected on the Carat Portal transaction status query service.
Call details#
- Resource:
/v3/recharge/{nit} - HTTP Method:
GET - Request format:
query string - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
Authorization | Authenticity signature in Bearer {signature} format. Learn more.Example: Bearer hh39458f73hf45324765ft349h5f73t4h95f34.This field is mandatory if the transaction was created with the signature process. | < 2000 AN | COND. |
Examples#
Below is an example of the recharge query service call using the cURL tool.
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Request parameters#
The table below describes the request parameters of the recharge query service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
nit | Identification of the recharge transaction on Carat Portal | = 64 AN | YES |
merchantkey | Merchant key on Carat Portal used on the recharge transaction. | < 80 AN | YES |
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 recharge query service:
| Parameter | Description | Format |
|---|---|---|
status | Status of the recharge transaction on Carat Portal. Learn more. | = 3 AN |
order_id | Order code generated by the store. | < 20 AN |
merchant_usn | USN of the transaction generated by the store. | < 12 N |
send_payment_methods | Flag indicating wether payment methods should be sent on the next transaction. It will have the value true when positive. | < 5 N |
| esitef | ||
code | Carat Portal response code. Any code different from 0(zero) means failure. Learn more. | < 4 N |
message | Carat Portal response message. | < 500 AN |
usn | USN of the recharge transaction on Carat Portal | = 15 N |
| authorizers[] This field adds a list of elements. | ||
name | Authorizer name | = 3 AN |
code | Response code returned by authorizer | = 3 AN |
message | Message returned by the authorizer | < 500 AN |
| acquirer | ||
branch_code | Recharge branch code | < 5 N |
merchant_code | Merchant code registered on the acquirer | < 15 N |
| authorization | ||
confirmation_data | Confirmation code | < 128 AN |
authorizer_date | Authorization date on the authorizer in MMDD format | = 4 N |
authorizer_time | Authorization time on the authorizer in HHmmSS format | = 6 N |
host_usn | Host USN | < 20 N |
sitef_usn | SiTef USN | < 10 N |
number | Authorization number | < 6 N |
| customer | ||
total_copies | Number of copies of the customer receipt | < 2 N |
receipt | Customer receipt | < 4000 AN |
| merchant | ||
total_copies | Number of copies of the merchant receipt | < 2 N |
receipt | Merchant receipt | < 4000 AN |
| payment_methods | ||
max | Maximum number of payment methods | < 2 N |
| payment_methods.available[] This field adds a list of available payment methods. | ||
name | Name of the available payment method. Learn more. | < 200 AN |
| payment This element is only returned if a payment related to a recharged was sent. | ||
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
amount | Amount of the payment, the same sent on the creation of the payment transaction. | < 12 AN |
type | Payment type of the chosen authorizer:
| = 1A |
authorizer_id | Authorizer ID on Carat Portal | < 5 N |
acquirer | Payment type | < 50 AN |
| payment.esitef | ||
usn | Carat Portal USN | < 15 AN |
date | Payment date on Carat Portal in DD/MM/YYYY hh:mm format. | < 19A |
| payment.sitef | ||
code | Response code returned by SiTef | = 3 AN |
| payment.customer | ||
receipt | Payment customer receipt | < 4000 AN |
| payment.merchant | ||
receipt | Payment merchant receipt | < 4000 AN |
| payment.authorization | ||
number | Payment authorization number | < 6 AN |
sitef_usn | SiTef USN | < 15 AN |
host_usn | Authorizer USN | < 15 AN |
tid | ID of the transaction on the authorizer, returned by some payment types. | < 40 AN |
eci | Eletronic commerce indicator returned by some payment types. | < 3 AN |
sitef_date | Payment date on SiTef in DD/MM/YYYY hh:mm format. | < 19 AN |
| payment.analysis | ||
status | Status of the transaction on the analysis institution. | = 3 AN |
code | Response code of the risk analysis. | < 4 AN |
message | Response message of the risk analysis. | < 100 AN |
| payment.extra_param[] | ||
key | Extra parameter key | N/A |
value | Extra parameter value | N/A |
| hashes
Hashes to indicate changes on recharge tables
| general | General hash. Indicates wether some of the specific hashes has been changed. | = 16 AN |
| wallet | Specific hash. If the recharge tables change, so does the returned hash, which has the following format:
<Network>:<Hash>:<Service 1>,<Service 2>, <Service N> Where:
- Network = Recharge network code
- Hash = Recharge network table hash.
- Service n = Network service type, which can be:
- F1-1 = National Phone Recharge
- F1-3 = Other Products Recharge
- Separators are two semicolons.
Example:
106:0D0C4FCB0D0C4FCB:F1-1,F1-3 | < 100 AN |Querying transactions from a group of merchants#
Carat Portal requires that the credentials (merchantkey) 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.