To use this example, don't forget to define the variable {{url}} to the value
cURL
curl
--request GET "https://{{url}}/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&generalhash=0000000000000000"
--verbose
To use this example, don't forget to define the variable {{url}} to the value
cURL
curl
--request GET "https://{{url}}/e-sitef/v3/rechargebranches?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&ddd=00&dealercode=1&generalhash=0000000000000000"
--verbose
Replace the field <nit> in the URL above with the NIT obtained in the transaction creation step.
Headers:
Content-Type: application/json
Request:
To use this example, don't forget to define the variable {{url}} to the value
cURL
curl
--request GET "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678/?merchantkey=ASDFGHJK12345678ASDFGHJK12345678"
--verbose
Carat Portal has two methods of merchant authentication on the REST recharge interface: authenticity POST or signature.
In the authenticity POST method, Carat Portal will send the data of the newly created recharge transaction to the registered authenticity URL of the merchant.
In the signature method, the merchant must have a public RSA encryption key registered on Carat Portal and prepare a JWT signature (JSON Web Tokens) to be sent in the Authorization header. In this case, the recharge transaction information will be returned directly in the response. Learn more.
Call details
Resource:/v3/recharge
HTTP Method:POST
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
Merchant's signature in the Bearer {signature} format. Example: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.
< 2000 AN
NO
Examples
Below are some examples of the recharge creation service call using the cURL tool.
Creating a recharge transaction sending all parameters
Request:
To use this example, don't forget to define the variable {{url}} with the value
The table below describes the request parameters of the recharge creation service:
Parameter
Description
Format
Mandatory
merchant_key
Merchant key registered on Carat Portal
< 80 A
YES
merchant_usn
Unique sequential number generated by the merchant
< 12 N
NO
order_id
Order identification code generated by the merchant
< 20 AN
NO
general_hash
Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).
If the store hadn't performed a recharge previously or hadn't saved a previously received value from Carat Portal, the value: 0000000000000000 can be passed to Carat Portal. If the general_hash is not sent, the store will be obliged to make all queries to obtain the data necessary for the next steps of the recharge.
= 16 A
NO
recharge_type
Type of the recharge to be performed.
Values:
normal – Cell phone top-up
others – Recharge for other types of products, such as games PIN, donations, iUSNrance or even cell phone recharge by other modalities.
invoice – Signature invoice payment
Default value: normal
= 6 A
NO
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 creation service:
Parameter
Description
Format
nit
Identification of the recharge transaction on Carat Portal
= 64 AN
merchant_id
Merchant ID on Carat Portal
< 15 AN
order_id
Order code generated by the merchant
< 20 AN
merchant_usn
Unique sequential number generated by the merchant
< 12 N
general_hash
Identification code of the table with the data related to the recharges (carriers, subsidiaries, ranges of values, validity of credits, among others).
= 16 AN
esitef Element that describes Carat Portal's response.
code
Carat Portal response code. Any code different from 0(zero) means failure. Learn more.
< 4 N
message
Carat Portal response message.
< 500 AN
Authenticity POST parameters
The table below describes the parameters sent by Carat Portal on the authenticity POST:
Parameter
Description
Format
nit
Identifier of the cancel transaction to be used in the next step of the flow.
= 64 AN
merchantId
Merchant code on Carat Portal.
< 15 AN
orderId
Order ID of the payment created by merchant
< 20 AN
merchantUSN
USN generated by the merchant for the payment
< 12 N
generalHash
Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).
= 16 AN
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.
Parameters sent by Carat Portal on HTTPS POST
Important:
Carat Portal uses the x-www-form-urlencoded media type to send the HTTPS POST. Therefore, the server must accept this type of media on the merchant's registered URL to receive POST HTTPS.
Parameter
Description
Format
nit
Identification of the recharge transaction on Carat Portal
= 64 AN
merchantId
Merchant ID on Carat Portal
< 15 AN
orderId
Order code generated by the merchant
< 20 AN
merchantUSN
Unique sequential number generated by the merchant
< 12 N
generalHash
Identification code of the table with the data related to the recharges (carriers, subsidiaries, ranges of values, validity of credits, among others).
= 16 AN
List Dealers
Brazil
Call details
Resource:/v3/rechargedealers
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.
This field is mandatory if the transaction was created with the signature process.
< 2000 AN
COND.
Examples
Below are some examples of the list dealers service call using the cURL tool.
List dealers of normal recharge
Request:
To use this example, don't forget to define the variable {{url}} with the value
Bash
curl
--request GET "https://{{url}}/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&generalhash=0000000000000000"
--verbose
The table below describes the request parameters of the list dealers service:
Parameter
Description
Format
Mandatory
nit
Identification of the recharge transaction on Carat Portal
= 64 A
SIM
generalhash
Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).
= 16 A
NÃO
Response parameters
If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the list dealers service:
Parameter
Description
Format
status
Status of the recharge transaction on Carat Portal. Learn more.
= 3 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
authorizer
code
Response code returned by the authorizer
< 4 AN
message
Message returned by the authorizer
< 64 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
dealers[]
code
Dealer code
= 3 N
name
Dealer name
< 100 AN
dealers[].branches[]
code
Branch code
= 11 N
name
Branch name
< 100 AN
questions[] This field adds a list of questions for positive confirmation. The returned questions must, necessarily, be answered by the user and have their answers sent to Carat Portal in the next step (list branch data).
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
Return of the questions.rule field
Rule
Description
0
Operator keyboard
1
PinPad (Not applicable)
2
Magnetic track reading on PIN PAD (Not applicable)
3
Automation (The question should not be presented to the operator / customer to collect the response. In this case, the automation itself must answer the question without operator / customer intervention).
4
Supervisor password (not PINPAD)
5
Operator keyboard with double typing. The <Display> must contain two texts, the first one refers to the request for the input of the data and the second, refers to the confirmation of the input of the data, which must be the same as the first.
The texts must be separated by ; as informed below.
<Display> = Text for 1st collection; Text for 2nd collection (confirmation)
6
Barcode reader
7
Typing with confirmation (In this case, a screen must be displayed for confirmation of the collected data).
Return of the questions.type field
Type
Description
A
Alphabetical.
AN
Special alphanumeric (ans).
LN
Letters (not accented) and numbers.
Nx
Numeric where x is the number of decimal digits supported.
Vx
Value with x decimal digits.
S
Menu type Yes / No.
Sc
Menu type Yes / No conditional. If the input is "No", the transaction must be aborted.
M
Free menu. In this case, the field will have the following format: the menu text must be separated by a | character from the options. The options, in turn, should consist of index and text separated by :, while one option is separated by the other by ^. That is: = |<option 1>^<option 2>^...^ At where, = Menu header text (Ex: Choose the banner of the card) = : (Ex: 1:Visa)
Mc
Free menu with confirmation. Here is the Free Menu rule, where: = |
M0
Free menu type 0 (zero). (Not applicable) It follows the rule of the Free Menu with confirmation, however, the selection indexes of the menu in the display must be suppressed and only selected with the POS arrows. Free Menu Display Example: 1 – Yes 2 – No Sample Free Menu Display Type 0: Yes No
List Branch Data
Brazil
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.
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
Bash
curl
--request GET "https://{{url}}/e-sitef/v3/rechargebranches?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&ddd=00&dealercode=1&generalhash=0000000000000000"
--verbose
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:
If there are no fields to be collected, only the TypeN field 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 (types 02 and 03) 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 input 1: typing the first line of the cheque 2: 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 sale 01 - Pre-dated 02 - Installments without interest 03 - 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.
---
Recharge Effectuation
Brazil
Call details
Resource:/v3/recharge/{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.
Identity document of the customer. Use alphanumeric characters only
< 20 AN
NO
merchant_key
Merchant key registered on Carat Portal. Must be the same merchant used to do the recharge.
< 80 AN
YES*
payment.installment
number
Number of installments
< 2 N
YES*
type
Installment financing type: 3 - installments with interest 4 - installments without interest (use this value as default for spot sales) 6 - installments with interest (IATA) 7 - installments without interest (IATA)
= 1 N
YES*
payment.card
number
Card number.
< 19 N
YES*
token
Card token stored on Carat Portal.
= 88 AN
YES*
security_code
Optional field, if sent, the main SiTef merchant code will be used instead of the recurrence code (which does not require a security code). It's mandatory depending on the agreement signed with the Card Administrators.
< 5 N
COND.
expiry_date
Expiry date in MMYY format
= 4 N
YES*
payment.extra_param[]
This field adds a list of extra parameters.
key
Extra parameter key
N/A
NO
value
Extra parameter value
N/A
NO
used_payment_methods[]
Used payment methods. This field adds a list of values that must be sent as described below.
Sending the used_payment_methods field
The store must use the used_payment_methods field itself to indicate to Carat Portal which payment methods were used to pay for a particular transaction, such as a recharge.
The amount of data to be written to the used_payment_methods field is limited by the payment_methods.max field. If, for example, the value 3 has been received in the payment_methods.max field, then the store can only store 3 information in the used_payment_methods field.
For each used payment method, an element (given) must be saved in the used_payment_methods field. The data to be saved in the used_payment_methods field has the following format:
TypeN: indicates the used payment method (as shown in the table above).
AmountN: indicates the amount used with this payment method, with two decimal digits, without the comma.
IDCollectionNn: indicates the field ID that was collected by the store (as shown in the table above).
CollectionDataNn: Indicates the content collected by the store for this field.
Notes:
If for a given payment method no field must be collected by the store, the used_payment_methods field must be valued with the following data: TypeN:AmountN.
The consistency of the values (sum of the various used payment methods, totaling the value of the transaction made) must be done by the store, and Carat Portal will only use the values the same way they were sent.
Example
Let's assume that in the execution of a recharge transaction, the store got the value 2 in the payment_methods.max field and the following values of the used_payment_methods field:
00
02:03-07-10-13(5,125)
03:10
The value 2 received in the payment_methods.max field indicates to the store that the payment of the recharge can only be done with a maximum of 2 different payment methods.
Assuming that the payment of the recharge was done as follows: R$ 30.00 in cash and R$ 20.00 with debit card processed by the acquirer Rede (Destination Network = 5; Host USN = 123456789; Confirmation data = 0520200001A6). In this case, the used_payment_methods field should be valued with the following data:
00:3000
02:2000:03:5-07:123456789-10:0520200001A6
Sending card data for payment
If it's desired to send the card token stored on Carat Portal, the other card data ( card.number, card.expiry_date) will not be considered. If you want to send the open card data, the token should not be sent.
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 effectuation 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
tv_package_subscription_codes[]
TV package subscription codes.
< 32 AN
resubmit_transaction
If this field receives the value true, the merchant must resend the recharge effectuation request with the answers field filled in as follows:
"answers":[{"code":"126","description":"<one the codes returned in the tv_package_subscription_codes field>"}]
In this case, the transaction status will be returned as AGU.
This flow is only possible on a TV Recharge.
T/F
send_payment_methods
Flag that indicates that the payment methods must be sent on the next transaction. It will have the value true when positive.
< 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
usn
USN of the recharge transaction on Carat Portal
= 15 N
sitef
code
SiTef response code
= 3 AN
message
SiTef response message
< 500 AN
host
code
Response code returned by the authorizer
< 4 AN
message
Message returned by the authorizer
< 64 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
hashes
general
Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).
= 16 AN
wallet
Wallet hash.
< 32 AN
payment_methods
max
Maximum number of payment methods
< 2 N
payment_methods.available[] This field adds a list of available payment methods.
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:
B = boleto
C = credit
D = debit
P = credit card Private Label
T = bank transfer
G = gift card
O = other payment methods
= 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
Important:
In the case of recharges of other products (pins, games), the pin will be returned only once as part of the payment.customer.receipt field. Because it is a sensitive field, Carat Portal does not store it, so subsequent status queries will not return the pin. If a problem occurs after the return of the pin by Carat Portal, the pin can't be recovered and it will be necessary to generate another pin.
---
Recharge Confirmation
Brazil
Call details
Resource:/v3/recharge/{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.
The table below describes the request parameters of the recharge confirmation service:
Parameter
Description
Format
Mandatory
confirm
It must receive the value true if it’s desired to confirm the recharge and its associated payment (if it exists). It must be set to false to undo the recharge and its associated payment (if any).
< 5 AN
YES
merchant_key
Merchant key on Carat Portal used on the recharge transaction.
< 80 AN
YES
used_payment_methods[]
Payment methods used to recharge. The user must follow the same rules described in Recharge effectuation service corresponding chapter to fill this field. In the case of TIM recharge, it is mandatory to send this field if you do not want the “Other forms” payment type (code 99) to be assumed.
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 recharge confirmation service:
Parameter
Description
Format
status
Status of the recharge transaction on Carat Portal. Learn more.
= 3 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
payment
status
Status of the payment transaction on Carat Portal, if it exists. Learn more.
