Initializing a Recharge transaction

Transaction creation process

The transaction creation process must follow these steps:

• The transaction is created according to the parameters sent in the request key and represented by a JSON object via POST in the request;
• The merchant receives a success or error message, formatted as XML or JSON, according to the response_type parameter in the URL sent when starting a transaction.

URL to start a transaction via HTTPS POST:

Homologation environment:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/[response_type].se
Production environment:
https://esitef-ec.softwareexpress.com.br/e-sitef/init/[response_type].se

Attention: The IP should never be used instead of the domain esitef-ec.softwareexpress.com.br (or esitef-homologacao.softwareexpress.com.br for the homologation environment). IP can change at any time and without notice, so it is important to always use the domain to access e-SiTef.

POST parameters:

• Key: request;
• Value: JSON object;
• [response_type]: json or xml;

JSON request example (JavaScriptObjectNotation):

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/json.se

Basic JSON request example:

{
    "merchant_id": "codigoDaLoja",
    "amount": "1800"
}

JSON object request with some additional parameters:

{
    "merchant_id": "codigoDaLoja",
    "order_id": "123456",
    "installments": "4",
    "recharge_included":"true",
    "recharge":{
        "dealer_code":"2",
        "phone":{
            "number":"87654321",
            "ddd":"11"
        }
    }
}

Test tools

For initial testing in this interface, if necessary, some tools can be used in order to better understand REST communication:

• Application for Windows/Linux/Mac:
  • POSTMAN
• Firefox extension:
  • RESTClient

Sample screens of these tools:

Request parameters

To initiate a transaction in the new HTML payment interface, the following parameters can be initially filled in JSON format:

{
    "merchant_id": "codigoDaLoja",
    "recharge_included":"true",
    "recharge":{ }
}

Parameter	Description	Format	Mandatory
amount	Total amount that will be paid by the customer. Format: Must be sent in cents. Ex.: 1000 (10 real).	< 12 N	YES
recharge_included	Notifies that a recharge will be included. Allowed values: true – if a recharge will be included. false – if a recharge will not be included. Default value - false	< 5 A	YES
recharge	RECHARGE object. Contains information related to a recharge transaction.		NO

RECHARGE (recharge)

{
    "dealer_code": "1",
    "phone": { },
}

Parameter	Description	Format	Mandatory
dealer_code	Dealer code.	< 3 N	NO
phone	PHONE object. Contains information related to the phone.		NO

PHONE (phone)

{
    "number": "123456789",
    "ddd": "11",
}

Parameter	Description	Format	Mandatory
number	Phone number.	< 20 N	NO
ddd	Phone area code.	< 4 N	NO

Response parameters

The response of the transaction creation operation (JSON format):

{
  "responseCode": 0,
  "description": "OK. Transaction successful.",
  "url": "https:// esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
  "nsuesitef": "123456789012345",
  "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
}

The returned fields are described in table below:

Parameter	Description	Format
responseCode	e-SiTef response code. Any code different from 0(zero) means failure. Learn more.	< 5 N
description	Response description.	< 1024 A
url	Redirection URL to begin the payment.	< 256 A
nit	Transaction identifier on e-SiTef.	= 64 A
nsuesitef	USN (Unique Sequential Number) of the transaction on e-SiTef.	= 15 A