Recharge effectuation service
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.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 recharge effectuation service call using the cURL tool.
Recharge type normal with payment#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Recharge type normal without payment#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
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:
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#
The table below describes the request parameters of the recharge effectuation service:
| Parameter | Description | Format | Mandatory | |||
|---|---|---|---|---|---|---|
nit | Identification of the recharge transaction on Carat Portal | = 64 AN | YES | |||
amount | Recharge amount in cents | < 12 N | YES | |||
amount_key | Recharge amount key | < 10 AN | NO | |||
terminal_type | 01 - POS02 - TU03 - TAS04 - Internet05 - POS-Sitef/POS | = 2 N | NO | |||
cpf | Customer CPF | < 20 AN | NO | |||
cnpj | Customer CNPJ | < 20 AN | NO | |||
zip_code | Customer zip code | < 9 AN | NO | |||
| hashes | ||||||
general | Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others). | = 16 AN | NO | |||
| dealer | ||||||
code | Dealer code | < 3 N | YES | |||
type_code | Dealer type code | < 2 N | YES | |||
| dealer.branch | ||||||
code | Dealer branch code. Only mandatory for recharge type others. | 11 N | COND. | |||
| phone | ||||||
phone.ddd | Phone area code (DDD). Only mandatory for recharge type normal. | = 2 N | COND. | |||
phone.number | Phone number. Only mandatory for recharge type normal. | < 9 N | COND. | |||
| answers[] | This field adds a list of answers. Mandatory if questions were received on the list branch data service. | |||||
code | Code of the question to be answered | < 20 AN | COND. | |||
description | Answer of the question | < 200 AN | COND. | |||
| invoice | This object contains mandatory fields for invoice payment (recharge type | |||||
bar_code | Bar code of the chosen invoice. | = 48 N | YES for invoice type | |||
description | Description of the chosen invoice. | < 64 AN | YES for invoice type | |||
expiry_date | Expiry date of the chosen invoice in DDMMYYYY format. | = 8 N | YES for invoice type | |||
reference_data | Reference data of the chosen invoice. | < 32 AN | YES for invoice type | |||
echo | echo field value as received on the list branch data call. | < 11 N | YES for invoice type | |||
| payment | This element should only be sent if you want to make a payment linked to the recharge.* | |||||
amount | Payment amount in cents | < 12 N | YES* | |||
authorizer_id | Authorizer ID on Carat Portal. Learn more. | < 5 N | YES* | |||
customer_id | 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 interest4 - 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:AmountN:IDCollectionN1:CollectionDataN1-IDCollectionN2:CollectionDataN2-...-IDCollectionNn:CollectionDataNn
Where:
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:
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:
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. | ||
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 |
Important:
In the case of recharges of other products (pins, games), the pin will be returned only once as part of the
payment.customer.receiptfield. 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.