Create Recharge service

Overview#

Carat Portal has two interfaces for integration with the virtual store, HTTPS POST and HTTPS Web Services, enabling the proper way of interaction between the store and Carat Portal, according to the programming language and the platform of the virtual store.

The HTML interface was defined to have a simple and quick integration with the payment method and the existing services on Carat Portal, without losing its flexibility. The default interface has only two required parameters, performing the collection of other parameters on the portal itself or through settings made by the store manager on Carat Portal's back office. However, if the virtual store wants to send definitions or restrictions for a particular service, acquirer or even the number of installments, it can be done through the set of parameters sent at the beginning of the transaction, before redirecting the client.

Flow#

The payment flow is executed by the merchant after the customer completes the purchase.

The merchant must initiate the transaction with Carat Portal by submitting the purchase data as shown below:

The payment flow without redirection consists of the following steps:

After the customer completes the purchase, the merchant creates a new transaction on Carat Portal, through a POST in the URL to start a transaction, informing all necessary parameters. Learn more.
As the POST response, the merchant will receive an URL from Carat Portal for redirecting the customer. This URL will be different for each recharge transaction.
The customer will fill the recharge information such as the dealer, DDD, phone number and amount, and will visualize the information associated to the selected amount (expiration, bonus, etc.).
The customer will follow the payment flow according to the informed authorizer, and ends the payment.
In the final step of the payment, the payment and recharge transactions will be confirmed on the authorizer and on the dealer respectively.
At the end of the payment flow, Carat Portal will redirect the customer back to the store, according to the configuration of return URLs already informed in the merchant registration, or to the back_url's sent on the creation of the payment transaction.

For each payment transaction status change on Carat Portal, the merchant will receive a status notification POST, informing its status. Learn more.

All outgoing calls will be answered synchronously except for the status notification that will be performed by Carat Portal asynchronously.

Initializing a Recharge transaction#

To initiate a HTML recharge, see the quickstart document.

Performing a recharge transaction#

When accessing the url returned by transaction creation service, the recharge value selection screen will be returned as shown below:

Fluxo de recarga HTML

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 Carat Portal.

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:

POSTMAN

RESTClient

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`	Carat Portal 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 Carat Portal.	= 64 A
`nsuesitef`	USN (Unique Sequential Number) of the transaction on Carat Portal.	= 15 A

Home