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:///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
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:///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
{
"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": "[email protected]",
"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":"[email protected]",
"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":"[email protected]",
"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"
}
Updated 15 days ago