Home

Overview

Quick start

This guide presents the merchant registration process, using Carat Portal's REST interface.

What you'll need#

  • A merchant registered on Carat Portal with permission for consuming this API
  • A tool capable of making HTTP calls, such as Postman, REST Client or cURL
  • An application capable of receiving POST HTTPS calls, if the authenticity post is used

Authenticity POST x signature#

Carat Portal has two methods of merchant authentication on the REST merchant creation, editing and query interface: authenticity POST or signature.

In the authenticity POST method, Carat Portal 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 Carat Portal and prepare a JWT signature (JSON Web Tokens) to be sent in the Authorization header. Learn more.

Creating a token#

Request method: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/token/merchants

Headers:

  • Content-Type: application/json
  • merchant_id: {your merchant id}
  • merchant_key: {your merchant key}

Request:

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/token/merchants"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--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("token = " + request.get("token"));
// ...
// stores the token
// ...
return new ResponseEntity<>("OK", HttpStatus.OK);
}
}

Response:

{
"response_code": 0,
"response_message": "OK. Transaction successful."
}

Learn more about this service.

Creating the merchant#

Request method: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/merchants

Fill the <id> field in the URL above with the ID of the merchant to be created.

Headers:

  • Content-Type: application/json
  • merchant_id: {your merchant id}
  • merchant_key: {your merchant key}
  • token: {token obtained in the previous step}
  • Authorization: {signature if JWT signature is used}

Request:

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

{
"fantasy_name": "Teste de Loja",
"corporate_name": "Testes de Loja Ltda.",
"soft_descriptor": {
"fantasy_name": "Sub-comércio da Loja",
"country": "BR",
"mcc": "1234",
"id": "123456"
},
"subacquirer_group": {
"create": "true",
"id": "123456",
"cnpj": "12345678901234"
},
"domain": "www.testeloja.com",
"cnpj": "123123123123",
"address": "Rua do Teste, 123",
"city": "São Teste",
"state": "SP",
"zip_code": "12345678",
"phone_number": "11912341234",
"email": "testeloja@teste.com",
"transactional_urls": {
"status": "https://www.testeloja.com/status",
"authenticity": "https://www.testeloja.com/autent",
"hash": "https://www.testeloja.com/hash"
},
"return_urls": {
"success": "https://www.testeloja.com/sucesso",
"failure": "https://www.testeloja.com/fracasso",
"cancel": "https://www.testeloja.com/cancel"
},
"permissions": {
"payment": "true",
"pre_authorization": "false",
"recharge": "false",
"risk_analysis": "true",
"schedule": "true",
"iata": "false",
"card_store": "false",
"payment_link": "true"
},
"establishments": [
{
"code": "00000000123",
"routing_id": "1125",
"subacquirer_group_id": "123456"
},
{
"code": "00000000321",
"routing_id": "1005"
}
],
"authorizers": [
{
"id": "1",
"routing_id": "1125",
"min_installments_amount": "100",
"max_installments_without_interest": "1",
"max_installments_with_interest": "12",
"enable_subacquirer_group": "true"
},
{
"id": "2",
"routing_id": "201",
"min_installments_amount": "100",
"max_installments_without_interest": "1",
"max_installments_with_interest": "12",
"parameters": {
"merchantId": "8h37e9e23oe",
"merchantKey": "b9f374t5983t745f873tb45f93b4f2293b485ft34"
}
}
]
}
curl
--request POST "https://{{url}}/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "token: 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--data-binary
{
"cnpj":"123123123123",
"fantasy_name":"Teste de Loja",
"corporate_name":"Testes de Loja Ltda.",
"soft_descriptor":{
"fantasy_name":"Sub-comércio da Loja",
"country":"BR",
"mcc":"1234",
"id":"123456"
},
"subacquirer_group":{
"create":"true",
"id":"123456",
"cnpj":"12345678901234"
},
"domain":"www.testeloja.com",
"address":"Rua do Teste, 123",
"city":"São Teste",
"state":"SP",
"zip_code":"12345678",
"phone_number":"11912341234",
"email":"testeloja@teste.com",
"transactional_urls":{
"status":"https://www.testeloja.com/status",
"authenticity":"https://www.testeloja.com/autent",
"hash":"https://www.testeloja.com/hash"
},
"return_urls":{
"success":"https://www.testeloja.com/sucesso",
"failure":"https://www.testeloja.com/fracasso",
"cancel":"https://www.testeloja.com/cancel"
},
"permissions":{
"payment":"true",
"pre_authorization":"false",
"recharge":"false",
"risk_analysis":"true",
"schedule":"true",
"iata":"false",
"card_store":"false",
"payment_link":"true"
},
"establishments":[
{
"code":"00000000123",
"routing_id":"1125",
"subacquirer_group_id":"123456"
},
{
"code":"00000000321",
"routing_id":"1005"
}
],
"authorizers":[
{
"id":"1",
"routing_id":"1125",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"enable_subacquirer_group":"true"
},
{
"id":"2",
"routing_id":"201",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"parameters":{
"merchantId":"8h37e9e23oe",
"merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
}
}
]
}
--verbose
curl
--request POST "https://{{url}}/e-sitef/api/v1/merchants"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "token: 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--data-binary
{
"cnpj":"123123123123",
"fantasy_name":"Teste de Loja",
"corporate_name":"Testes de Loja Ltda.",
"soft_descriptor":{
"fantasy_name":"Sub-comércio da Loja",
"country":"BR",
"mcc":"1234",
"id":"123456"
},
"subacquirer_group":{
"create":"true",
"id":"123456",
"cnpj":"12345678901234"
},
"domain":"www.testeloja.com",
"address":"Rua do Teste, 123",
"city":"São Teste",
"state":"SP",
"zip_code":"12345678",
"phone_number":"11912341234",
"email":"testeloja@teste.com",
"transactional_urls":{
"status":"https://www.testeloja.com/status",
"authenticity":"https://www.testeloja.com/autent",
"hash":"https://www.testeloja.com/hash"
},
"return_urls":{
"success":"https://www.testeloja.com/sucesso",
"failure":"https://www.testeloja.com/fracasso",
"cancel":"https://www.testeloja.com/cancel"
},
"permissions":{
"payment":"true",
"pre_authorization":"false",
"recharge":"false",
"risk_analysis":"true",
"schedule":"true",
"iata":"false",
"card_store":"false",
"payment_link":"true"
},
"establishments":[
{
"code":"00000000123",
"routing_id":"1125",
"subacquirer_group_id":"123456"
},
{
"code":"00000000321",
"routing_id":"1005"
}
],
"authorizers":[
{
"id":"1",
"routing_id":"1125",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"enable_subacquirer_group":"true"
},
{
"id":"2",
"routing_id":"201",
"min_installments_amount":"100",
"max_installments_without_interest":"1",
"max_installments_with_interest":"12",
"parameters":{
"merchantId":"8h37e9e23oe",
"merchantKey":"b9f374t5983t745f873tb45f93b4f2293b485ft34"
}
}
]
}
--verbose

Response:

{
"id": "qereIoinsd3d",
"key": "9B71234TB12D938T9384TDB294T923D412T938D1293D4B923D",
"response_code": "0",
"response_message": "OK"
}

Learn more about this service.