List branch data service
Call details for recharge type normal#
- Resource:
/v3/rechargebranches - HTTP Method:
GET - Request format:
query string - Response format:
JSON
Call details for recharge type others#
- Resource:
/v3/rechargebranches/{nit} - HTTP Method:
PUT - Request format:
JSON - Response format:
JSON
Call details for recharge type invoice#
- Resource:
/v3/rechargebranches/{nit} - HTTP Method:
PUT - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
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 are some examples of the list branch data service call using the cURL tool.
List branch data for recharge type normal#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
List branch data for recharge type others#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
List branch data for recharge type invoice#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Request parameters for recharge type normal#
The table below describes the request parameters of the list branch data service for recharge type normal:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
nit | Identification of the recharge transaction on Carat Portal | = 64 AN | YES |
ddd | Phone area code | = 2 N | YES |
dealercode | Dealer code | < 3 N | YES |
generalhash | Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others). | = 16 AN | NO |
Request parameters for recharge type others#
The table below describes the request parameters of the list branch data service for recharge type others:
| Parameter | Description | Format | Mandatory | |||
|---|---|---|---|---|---|---|
nit | Identification of the recharge transaction on Carat Portal. Attention: This field goes in the URL of the request, not in the body. | = 64 AN | YES | |||
ddd | Phone area code (DDD) | = 2 N | NO | |||
general_hash | Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others). | = 16 AN | NO | |||
| dealer | Dealer information. This information is returned on the list dealers call. | |||||
code | Dealer code | < 3 N | YES | |||
type_code | Dealer type code | < 3 N | YES | |||
| dealer.branch | Information about the dealer's affiliate | |||||
code | Dealer branch code | < 11 N | YES | |||
| answers[] | This field adds a list of answers. Mandatory if questions were received on the list dealers service. | |||||
code | Question code to be answered (questions.id of the list dealers service response) | < 20 AN | COND. | |||
description | Answer of the question | < 200 AN | COND. | |||
Request parameters for recharge type invoice#
The table below describes the request parameters of the list branch data service for recharge type invoice:
| Parameter | Description | Format | Mandatory | |||
|---|---|---|---|---|---|---|
nit | Identification of the recharge transaction on Carat Portal. Attention: This field goes in the URL of the request, not in the body. | = 64 AN | YES | |||
general_hash | Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others). | = 16 AN | NO | |||
| dealer | Dealer information. This information is returned on the list dealers call. | |||||
code | Dealer code | < 3 N | YES | |||
| dealer.branch | Information about the dealer's affiliate | |||||
code | Dealer branch code | < 11 N | YES | |||
| answers[] | This field adds a list of answers. Mandatory if questions were received on the list dealers service. | |||||
code | Question code to be answered (questions.id of the list dealers service response) | < 20 AN | COND. | |||
description | Answer of the question | < 200 AN | COND. | |||
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 list branch data service:
| Parameter | Description | Format |
|---|---|---|
status | Status of the recharge transaction on Carat Portal. Learn more. | = 3 AN |
invoice_holder_name | Invoice holder name | < 70 AN |
echo | Field to be resent for recharge of the type invoice | < 128 AN |
resubmit_transaction | Indicates that this transaction should be resent with the selected TV subscription code. | < 5 AN |
| 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 |
| sitef | ||
code | Response code returned by the authorizer | < 4 AN |
| hashes | ||
general | Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others). | = 16 AN |
| questions[] This field adds a list of questions for positive confirmation. The returned questions must be answered by the user and have their answers sent to Carat Portal in the next step (recharge) | ||
id | Question identification code | < 20 AN |
display | Text of the question to be presented | < 180 AN |
rule | Indicates where the data must be collected. Learn more. | < 2 AN |
min | Indicates the minimum response size | < 4 N |
max | Indicates the maximum response size | < 5 N |
type | Indicates the data type of the response to be collected. Learn more. | < 3 AN |
min_value | Indicates the minimum response value | < 3 N |
max_value | Indicates the maximum response value | < 3 N |
| general This field adds a list of general characteristics among the branches. | ||
message | General message. | < 101 AN |
| categories This field adds a list of categories. | ||
code | Category code | < 5 AN |
description | Descriptive text of the category | < 100 AN |
| categories.amount_ranges This field adds a list of amount ranges. | ||
message | Recharge information message | < 100 AN |
amount_key | Recharge amount key (to be sent when performing the recharge). | < 5 AN |
bonus_in_percentage | Recharge bonus in percentage of face value (to 2 decimal places: eg 1% = 100). | < 5 N |
bonus | Recharge bonus. | < 12 N |
payment_amount | Recharge cost. | < 12 N |
bonus_category | Bonus category (must be one of the values of categories.code). | < 5 AN |
expiry_date | Expiration period (in days). | < 4 N |
bonus_expiry_date | Expiration period of the bonus (in days). | < 4 N |
min_amount | Minimum value of the range, in cents. | < 12 N |
max_amount | Maximum value of the range, in cents. | < 12 N |
| categories.fixed_amounts This field adds a list of fixed amounts. | ||
message | Recharge information message | < 100 AN |
amount_key | Recharge amount key (to be sent when performing the recharge). | < 5 AN |
bonus_in_percentage | Recharge bonus in percentage of face value (to 2 decimal places: eg 1% = 100). | < 5 N |
bonus | Recharge bonus. | < 12 N |
payment_amount | Recharge cost. | < 12 N |
bonus_category | Bonus category (must be one of the values of categories.code). | < 5 AN |
expiry_date | Expiration period (in days). | < 4 N |
bonus_expiry_date | Expiration period of the bonus (in days). | < 4 N |
amount | Recharge amount, in cents. | < 12 N |
| payment_methods | ||
max | Maximum number of payment methods | < 2 N |
available | This field adds a list of available payment methods and their details. Learn more. | < 200 AN |
| host | ||
message | Institution name | < 16 AN |
code | Institution response code | < 12 AN |
| acquirer | ||
merchant_code | Establishment code | < 15 N |
| authorization | ||
number | Authorization number | < 6 AN |
sitef_usn | Sitef usn | < 6 N |
host_usn | Host usn | < 12 N |
authorizer_time | Authorizer response time HHMMSS | = 6 N |
authorizer_date | Authorizer response date MMDD | = 4 N |
| invoices This object contains fields returned on recharge transactions of type invoice | ||
expiry_date | Invoice expiration date in format AAAAMMDD | = 8 N |
consumption_reference | Invoice reference date in format MMAAAA | = 6 N |
bar_code | Invoice bar code | < 44 N |
amount | Invoice amount | < 12 N |
message | General message | < 64 AN |
Return of the payment_methods.available field#
The payment_methods.available field may contain one or more data for reading. Each read data has the following format:
TypeN:IDCollectionN1-IDCollectionN2-IDCollectionN3-...-IDCollectionNn
Where:
TypeN: indicates the allowed payment method.
| Type | Description |
|---|---|
00 | Money |
01 | Check |
02 | EFT Debit |
03 | EFT Credit |
10 | Electronic Ticket |
11 | Paper Ticket |
12 | Digital Wallet |
13 | PIX |
50 | EFT Cards |
99 | Other Forms |
Notes:
- If there are no fields to be collected, only the
TypeNfield is returned. - In the future, new payment methods can be added to this table. If the POS does not know one of these new methods, it should be prepared to "skip" only this method, without affecting its processing.
- The "EFT Card" payment method (type
50) is used to group all payment methods involving cards (types02and03) into a single type.
IDCollectionNn: Indicates the field ID that the POS must collect and send to SiTef.
| ID | Description | Meaning and Format |
|---|---|---|
01 | Cheque input type | 0: CMC-7 input1: typing the first line of the cheque2: typing the CMC-7 |
02 | Cheque data | - CMC-7 read or typed - Enter the first line of the cheque, in the following format: Compensation (3), Bank (3), Agency (4), C1 (1), Current Account (10), C2 (1), Cheque Number (6) and C3 (1), in this order. |
03 | Destination Network | Identification of the authorization of the EFT transaction (according to the Destination Network table from the SiTef specification). |
04 | SiTef USN of the EFT Transaction | Identification of the EFT transaction on SiTef. |
05 | SiTef date of the EFT Transaction (currently, not used) | Date of the EFT transaction on SiTef in DDMMYYYY format. |
06 | EFT Transaction Company Code | SiTef code for the Company used on the EFT transaction. |
07 | EFT Transaction Host USN | Identification of the EFT transaction on the Host. |
08 | EFT Transaction Host Date | Date of the EFT transaction on the Host, in DDMMYYYY format. |
09 | EFT Transaction Source Code | Establishment Code of the EFT transaction. |
10 | Confirmation data of the EFT transaction. | Field 9 returned when performing the EFT transaction. |
11 | EFT Transaction Authorization Code | Host Authorization Code for the EFT transaction. |
12 | Cheque Amount | Total Cheque Amount. A same cheque can be used to pay more than one account. |
13 | Destination Network - Complement | Complement of ID 03 (See note 1 below) |
14 | Card Issuer | Issuer of the card used on the EFT transaction. |
15 | Payment Type | 00 - spot sale01 - Pre-dated02 - Installments without interest03 - Installments with interest |
Notes:
The field with ID 13, different from the others, does not indicate a field to be collected. This field works as a complement to field ID 03, sending a list of allowed destination networks in the following format:
13 (Network1, Network2, ..., NetworkN)
That is, if only the field ID 03 is present, it must be a destination network, without any restriction of access to networks that can pay a particular transaction (Example: recharge). However, if the indicators ID 03 and 13 are present, the first indicates that the destination network must be collected, while the second indicates which destination networks are allowed to pay the recharge.
In addition, as the collection was indicated by ID 03, the POS must send the destination network to SiTef also via this ID (and not via ID 13).
In the future, new fields can be added to this table. If the POS does not recognize one of the new fields, it must be prepared to "skip" only this field, without affecting its process.