Home

Overview

Quick start

This guide shows the process of performing a recharge, using Carat Portal's REST web service interface.

What you'll need#

  • Active account on Carat Portal's homologation environment (obtained with our support team)
  • A tool capable of performing HTTP calls, such as Postman, REST Client or cURL

Creating the transaction#

HTTP method: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge

Headers:

  • Content-Type: application/json

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
"begin_recharge_request": {
"merchant_key": "XXXXXXXX"
}
}
curl
--request POST "https://{{url}}/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
"begin_recharge_request":{
"merchant_key":"XXXXXXXX"
}
}
--verbose

Receiving the authenticity POST:

@RestController
public class MyAuthenticityController {
@PostMapping(value = "/myauthenticity",
consumes = "application/x-www-form-urlencoded; charset=utf-8")
public ResponseEntity<String> myAuthenticity(@RequestParam Map<String, String> request) {
Log.info("nit = " + request.get("nit"));
// ...
// stores the recharge NIT
// ...
return new ResponseEntity<>("OK", HttpStatus.OK);
}
}

Response:

{
"begin_recharge_response": {
"esitef": {
"message": "OK. Transaction successful.",
"code": "0"
}
}
}

Learn more about this service.

Listing dealers#

HTTP method: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargedealers

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

curl
--request GET "https://{{url}}/e-sitef/v3/rechargedealers?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&generalhash=0000000000000000"
--verbose

Response:

{
"list_dealers_response": {
"status": "NOV",
"esitef": {
"message": "OK. Transaction successful.",
"code": "0"
},
"authorizer": {
"message": "",
"code": "000"
},
"hashes": {
"general": "09A9681D09A9681D"
},
"dealers": [
{
"name": "Vivo",
"code": "001"
},
{
"name": "Claro",
"code": "002"
},
{
"name": "Oi",
"code": "003"
},
{
"name": "Tim",
"code": "004"
}
]
}
}

Learn more about this service.

Listing branch data#

HTTP method: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/rechargebranches

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

curl
--request GET "https://{{url}}/e-sitef/v3/rechargebranches?nit=asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678&ddd=00&dealercode=1&generalhash=0000000000000000"
--verbose

Response:

{
"list_branch_data_response": {
"status": "NOV",
"esitef": {
"message": "OK. Transaction successful.",
"code": "0"
},
"sitef": {
"code": "000"
},
"hashes": {
"general": "09A9681D09A9681D"
},
"questions": [
{
"id": "5",
"display": "Qual o nome do seu pai?",
"rule": "3",
"min": "5",
"max": "30",
"type": "i"
}
],
"general": [
{
"message": "MENSAGEM DE TESTE"
}
],
"categories": [
{
"code": "01",
"description": "RECARGA",
"amount_ranges": [
{
"message": "MSG_FAIXA_1",
"amount_key": "7",
"bonus_in_percentage": "100",
"bonus": "50",
"payment_amount": "700",
"bonus_category": "1",
"expiry_date": "30",
"bonus_expiry_date": "15",
"min_amount": "500",
"max_amount": "10000"
},
{
"message": "MSG_FAIXA_2",
"amount_key": "8",
"bonus_in_percentage": "500",
"bonus_category": "2",
"min_amount": "1000",
"max_amount": "50000"
}
],
"fixed_amounts": [
{
"bonus": "50",
"message": "MSG_FIXO_1",
"amount": "300",
"amount_key": "1",
"bonus_category": "2",
"bonus_in_percentage": "200",
"payment_amount": "10",
"expiry_date": "60",
"bonus_expiry_date": "15"
},
{
"message": "MSG_FIXO_2",
"amount": "1500",
"amount_key": "2",
"payment_amount": "30"
},
{
"message": "MSG_FIXO_3",
"amount": "2000",
"amount_key": "3"
},
{
"amount": "2200",
"amount_key": "4",
"expiry_date": "90"
},
{
"message": "MSG_FIXO_4",
"amount": "5000",
"amount_key": "6",
"expiry_date": "120"
}
]
},
{
"code": "02",
"description": "SMS",
"amount_ranges": [],
"fixed_amounts": []
},
{
"code": "03",
"description": "PRIMEIRA_RECARGA",
"amount_ranges": [],
"fixed_amounts": []
}
],
"payment_methods": {
"max": "4",
"available": ["00", "01", "02:10", "03:10", "04:10", "05:10", "06:10"]
}
}
}

Learn more about this service.

Effecting the recharge#

Recharge with payment#

HTTP method: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/<nit>

Headers:

  • Content-Type: application/json

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
"do_recharge_request": {
"hashes": {
"general": "0000000000000000"
},
"dealer": {
"code": "1",
"type_code": "03",
"branch": {
"code": "98006000000"
}
},
"phone": {
"ddd": "11",
"number": "123456789"
},
"amount": "3000",
"amount_key": "3",
"used_payment_methods": ["11", "12"],
"answers": [
{
"code": "1",
"description": "response"
},
{
"code": "2",
"description": "response2"
}
],
"terminal_type": "03",
"cpf": "8298374982374",
"cnpj": "123121333000123",
"zip_code": "01310100",
"payment": {
"amount": "12",
"authorizer_id": "1",
"customer_id": "12341234",
"merchant_key": "OIAUSWHFN012375901J23047FNN00UYWHN0R871Y2ND87",
"installment": {
"number": "2",
"type": "4"
},
"card": {
"number": "1111111111111111",
"token": "",
"security_code": "123",
"expiry_date": "1222"
},
"extra_param": [
{
"key": "CRIPTO",
"value": "1"
}
]
}
}
}
curl
--request PUT "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
"do_recharge_request":{
"hashes":{
"general":"0000000000000000"
},
"dealer":{
"code":"1",
"type_code":"03",
"branch":{
"code":"98006000000"
}
},
"phone":{
"ddd":"11",
"number":"123456789"
},
"amount":"3000",
"amount_key":"3",
"used_payment_methods":[
"11",
"12"
],
"answers":[
{
"code":"1",
"description":"response"
},
{
"code":"2",
"description":"response2"
}
],
"terminal_type":"03",
"cpf":"8298374982374",
"cnpj":"123121333000123",
"zip_code":"01310100",
"payment":{
"amount":"12",
"authorizer_id":"1",
"customer_id":"12341234",
"merchant_key":"OIAUSWHFN012375901J23047FNN00UYWHN0R871Y2ND87",
"installment":{
"number":"2",
"type":"4"
},
"card":{
"number":"1111111111111111",
"token":"",
"security_code":"123",
"expiry_date":"1222"
},
"extra_param":[
{
"key":"CRIPTO",
"value":"1"
}
]
}
}
}
--verbose

Response:

{
"do_recharge_response": {
"status": "PPC",
"order_id": "12344231",
"merchant_usn": "5123",
"esitef": {
"message": "OK",
"code": "0",
"usn": "123456789012345"
},
"sitef": {
"message": "OK",
"code": "0"
},
"host": {
"message": "OK",
"code": "0"
},
"acquirer": {
"branch_code": "cod filial",
"merchant_code": "codigoEstab"
},
"authorization": {
"confirmation_data": "000033333",
"authorizer_date": "20150514",
"authorizer_time": "1100",
"host_usn": "11122",
"sitef_usn": "333",
"number": "332234"
},
"customer": {
"total_copies": 3,
"receipt": "COMPROVANTE DE RECARGA via do cliente"
},
"merchant": {
"total_copies": 3,
"receipt": "COMPROVANTE DE RECARGA via do estabelecimento"
},
"payment_methods": {
"max": 4,
"available": [
{
"name": "dinheiro"
},
{
"name": "cheque"
}
]
},
"payment": {
"status": "PPC",
"amount": "12",
"type": "C",
"esitef": {
"usn": "098765432109876",
"date": "12/12/2012 12:12"
},
"customer": {
"receipt": "nwiugrnboinb APROVADO via do cliente"
},
"merchant": {
"receipt": "nwiugrnboinb APROVADO via do estabelecimento "
},
"authorizer_id": "1",
"acquirer": "CIELO",
"authorization": {
"number": "163457212",
"sitef_usn": "456456",
"host_usn": "654654",
"tid": "7334312a2",
"eci": "fr3u214wf71",
"sitef_date": "12122012"
},
"analysis": {
"status": "PEN",
"code": "0",
"message": "aprovado"
},
"extra_param": [
{
"key": "CRIPTO",
"value": "1"
}
],
"sitef": {
"code": "000"
}
}
}
}

Recharge without payment#

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
"do_recharge_request": {
"dealer": {
"code": "1"
},
"phone": {
"ddd": "11",
"number": "123456789"
},
"amount": "3000"
}
}
curl
--request PUT "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
"do_recharge_request":{
"dealer":{
"code":"1"
},
"phone":{
"ddd":"11",
"number":"123456789"
},
"amount":"3000"
}
}
--verbose

Response:

{
"do_recharge_response": {
"status": "PPC",
"order_id": "12344231",
"merchant_usn": "5123",
"esitef": {
"message": "OK",
"code": "0",
"usn": "123456789012345"
},
"sitef": {
"message": "OK",
"code": "0"
},
"host": {
"message": "OK",
"code": "0"
},
"acquirer": {
"branch_code": "cod filial",
"merchant_code": "codigoEstab"
},
"authorization": {
"confirmation_data": "000033333",
"authorizer_date": "20150514",
"authorizer_time": "1100",
"host_usn": "11122",
"sitef_usn": "333",
"number": "332234"
},
"customer": {
"total_copies": 3,
"receipt": "COMPROVANTE DE RECARGA via do cliente"
},
"merchant": {
"total_copies": 3,
"receipt": "COMPROVANTE DE RECARGA via do estabelecimento"
},
"payment_methods": {
"max": 4,
"available": [
{
"name": "dinheiro"
},
{
"name": "cheque"
}
]
}
}
}

Learn more about this service.

Confirming the recharge#

HTTP method: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/<nit>

Headers:

  • Content-Type: application/json

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
"confirm_recharge_request": {
"confirm": "true",
"merchant_key": "AOSDJF210349H3R0374H874H3T7AHG90SF"
}
}
curl
--request PUT "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
"confirm_recharge_request":{
"confirm":"true",
"merchant_key":"AOSDJF210349H3R0374H874H3T7AHG90SF"
}
}
--verbose

Response:

{
"confirm_recharge_response": {
"esitef": {
"message": "OK",
"code": "0"
},
"status": "CON",
"payment": {
"status": "CON"
}
}
}

Learn more about this service.

Checking the recharge status#

HTTP method: PUT

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/<nit>

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
esitef-homologacao.softwareexpress.com.br

curl
--request GET "https://{{url}}/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678/?merchantkey=ASDFGHJK12345678ASDFGHJK12345678"
--verbose

Response:

{
"get_status_recharge_response": {
"status": "CON",
"esitef": {
"message": "OK",
"code": "0"
},
"authorizers": [
{
"name": "sitef",
"message": "textoExibicao",
"code": "codigoRespSitef"
},
{
"name": "nome operadora (186)",
"message": "OK",
"code": "196"
}
],
"acquirer": {
"branch_code": "cod filial",
"merchant_code": "codigoEstab"
},
"authorization": {
"confirmation_data": "000033333",
"authorizer_date": "20150514",
"authorizer_time": "1100",
"host_usn": "11122",
"sitef_usn": "333",
"number": "332234"
},
"customer": {
"total_copies": 3,
"receipt": "COMPROVANTE DE RECARGA mimimim cliente whiskas sache"
},
"merchant": {
"total_copies": 3,
"receipt": "COMPROVANTE DE RECARGA mimimim estabelecimento lorem ipsum"
},
"payment_methods": {
"max": 2,
"available": [
{
"name": "dinheiro"
},
{
"name": "cheque"
}
]
},
"payment": {
"status": "PPC",
"amount": "12",
"type": "C",
"esitef": {
"usn": "098765432109876",
"date": "12/12/2012 12:12"
},
"customer": {
"receipt": "nwiugrnboinbAPROVADOaoisuerhn"
},
"merchant": {
"receipt": "nwiugrnboinbAPROVADOaoisuerhn"
},
"authorizer_id": "1",
"acquirer": "CIELO",
"authorization": {
"number": "163457212",
"sitef_usn": "456456",
"host_usn": "654654",
"tid": "7334312a2",
"eci": "fr3u214wf71",
"sitef_date": "12122012"
},
"analysis": {
"status": "PEN",
"code": "0",
"message": "hahaha"
},
"extra_param": [
{
"key": "CRIPTO",
"value": "1"
}
],
"sitef": {
"code": "000"
}
}
}
}

Learn more about this service.