# Token Creation Service

import ResponseCodes from './codigos-de-resposta.md';
import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

Consuming the token generation service is mandatory for creating or editing a merchant. As a result from this operation, the virtual store will obtain a token on their authenticity URL, which will be necessary for the next step of the flow.

## Call details

<ApiDoc method="post" path="/e-sitef/api/v1/token/merchants" />

- **Resource**: `/v1/token/merchants`
- **HTTP Method**: `POST`
- **Response format**: `JSON`
- **Header parameters**:

|   Parameter    | Description                                                                                           |     Format     | Mandatory |
| :------------: | :---------------------------------------------------------------------------------------------------- | :------------: | :-------: |
| `merchant_id`  | Merchant code on Carat Portal. The production and certification codes will be different.              | <u><</u> 15 AN |    YES    |
| `merchant_key` | Merchant authentication key on Carat Portal. The production and certification keys will be different. | <u><</u> 80 AN |    YES    |

## Example

**Request:**

To use this example, don't forget to define the variable `{{url}}` with the value<br/> **<URLPOSTMAN/>**

```bash
curl 
--request POST "https://{{url}}/e-sitef/api/v1/token/merchants"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose
```

**Authenticity POST:**

To use this example, don't forget to define the variable `{{url}}` with the value<br/> **<URLPOSTMAN/>**

```bash
curl  -X POST \
  https://urlDeAutenticidadeDaLoja.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d 'token=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
```

**Response:**

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

<ResponseCodes />

## Authenticity POST parameters

The table below describes the parameters sent by Carat Portal on the authenticity POST:

| Parameter | Description                                    | Format  |
| --------- | ---------------------------------------------- | ------- |
| `token`   | Token to be sent in the next step of the flow. | = 66 AN |

Carat Portal can also send new parameters without previous warning, which means that the merchant's application must be prepared to receive additional fields and simply ignore them.

> **Attention:** It's essential that the site hosted on the merchant's Authenticity URL receives the token and responds with `HTTP 200`, as this is how Carat Portal considers it a successful POST.

## Response parameters

If successful, the HTTP response code will be `200`. Any other code must be interpreted as an error. The table below describes the response parameters of the token creation service:

| Parameter          | Description                                                                                                                  | Format          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `response_code`    | Carat Portal response code. Any code different from `0`(zero) means failure. [Learn more.](codigos-da-api.md#response-codes) | <u><</u> 4 N    |
| `response_message` | Carat Portal response message.                                                                                               | <u><</u> 500 AN |