REST Merchants Registration


To call any Carat Portal service, it's required that the merchant is registered by our Support and Production teams (even for interacting with the merchants registration API).s The merchants registration REST interface is recommended when there is a frequent need for registering new merchants on Carat Portal.

And to learn more about these nomenclatures (Bin, Software Express, Carat, e-Sitef) Learn more


To make a Web Service transaction, the whole communication must be done via HTTPS/TLS. It's important that the merchant's server supports encryption of a minimum of 128 bits. The merchant's server must make calls on specific addresses to do REST transactions.

Each service must be called using the base URL concatenated with the desired resource (see the chapter related to the service to be consumed). The HTTP method (GET, POST or PUT) indicates the expected action on the selected resource. Listed below are the base URLs of Carat Portal:

Production base URL:

Homologation base URL:

Every call received by the services will be responded synchronously.


Never use the IP instead of the domain. The IP can change at any time without previous warning, so it's important to use the domain when accessing Carat Portal.


Besides the response parameters of the services described in this specification, Carat Portal can return other parameters without previous warning.

It's important that the application is prepared to receive the unknown parameters besides the fields already specified and simply ignore them.


Merchant creation#

  • 1. The merchant begins the process requesting the generation of a token for accessing the merchants registering API.
    • 1.1. Carat Portal makes a HTTP POST on the authenticity URL of the merchant containing the token.
    • 1.2. The Virtual Store responds to the POST with HTTP code 200 OK.
    • 1.3. With a successful authenticity process, Carat Portal returns a success response to the merchant.
  • 2. Then, the Virtual Store sends merchant creation request, containing the previously obtained token.
    • 2.1. Carat Portal registers the merchant and returns a success response.

Merchant editing#

The flow for altering a merchant is the same as the creation, with the difference that the merchant editing service must be called in the second step instead.