Recharge creation service

Authenticity POST x signature

e-SiTef has two methods of merchant authentication on the REST recharge interface: authenticity POST or signature.

In the authenticity POST method, e-SiTef 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 e-SiTef 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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX",
      "merchant_usn":"2398",
      "order_id":"023748",
      "general_hash":"0000000000000000",
      "recharge_type":"normal"
   }
}
--verbose

Response:

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

Creating a recharge transaction sending only the required parameters

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX"
   }
}
--verbose

Response:

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

Creating a recharge transaction with signature

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge"
--header "Content-Type: application/json"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc"
--data-binary
{
   "begin_recharge_request":{
      "merchant_key":"XXXXXXXX",
      "merchant_usn":"1446681016",
      "order_id":"13014858663",
      "general_hash":"0000000000000000"
   }
}
--verbose

Response:

{
   "begin_recharge_response":{
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0"
      },
      "nit": "jhadafsafhjhasdfghiyuw43u8785345jksjknsmnnsjkfkiu34u98ynksnn3535",
      "merchant_id": "XXXXXXXX",
      "order_id": "13014858663",
      "merchant_usn": "1446681016",
      "general_hash": "AF32810AAF32810A"
   }
}

Request parameters

The table below describes the request parameters of the recharge creation service:

Parameter	Description	Format	Mandatory
`merchant_key`	Merchant key registered on e-SiTef	< 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 e-SiTef, the value: `0000000000000000` can be passed to e-SiTef. 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:

Parâmetro	Descrição	Formato
`nit`	Identification of the recharge transaction on e-SiTef	= 64 AN
`merchant_id`	Merchant ID on e-SiTef	< 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 e-SiTef's response.
`code`	e-SiTef response code. Any code different from `0`(zero) means failure. Learn more.	< 4 N
`message`	e-SiTef response message.	< 500 AN

Parameters sent by e-SiTef on HTTPS POST

Important:

e-SiTef 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 e-SiTef	= 64 AN
`merchantId`	Merchant ID on e-SiTef	< 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