# Pre-Authorization Creation

<BraEng />

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

The Pre-Authorization transaction flow is started by consuming the **beginTransaction** operation, which will generate an Carat Portal record of a transaction with status = `NOV`, and return the `nit` parameter to the application, which will identify this transaction.

A `nit` has a usage time set in **Carat Portal**. If this timeout exceeds the transaction, it will go beyond status `NOV` to the status` EXP`. In this case it will no longer be allowed to use the same `nit`, being necessary to consume the **beginTransaction** operation again to generate another valid `nit`.

## Risk Analysis

For transactions with risk analysis built-in, the [**same fields available on payment transactions should apply**](pagamento-rest-begin.md#creating-a-payment-with-risk-analysis-using-konduto-antifraud).

## Call details

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

- **Resource:** `/v1/transactions`
- **HTTP Method:** `POST`
- **Request format:** `JSON`
- **Response format:** `JSON`
- **Header parameters:**

| Parameter      | Description                                                                                | Format  | Mandatory |
| -------------- | ------------------------------------------------------------------------------------------ | ------- | --------- |
| `Content-Type` | Fixed value "application/json"                                                             | = 15 A  | Yes       |
| `merchant_id`  | Carat Portal store's ID. Production and certification IDs are different.                   | ≤ 15 A  | Yes       |
| `merchant_key` | Store authentication key in Carat Portal. Production and certification keys are different. | \< 80 A | Yes       |

## Examples

Below there are some examples of calling the pre-authorization creation service using the **cURL** tool.

## Pre-Authorization

**Request:**

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

```json
curl
--request POST "https://{{url}}/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"preauthorization"
}
--verbose
```

**Response:**

```json
{
  "code": "0",
  "message": "OK. Transaction successful.",
  "pre_authorization": {
    "status": "NOV",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "orderID",
    "merchant_usn": "20190101",
    "amount": "100"
  }
}
```

## Request Parameter

<FISERV>

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Format",
    "h-3": "Mandatory",
    "0-0": "`amount`",
    "0-1": "Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas",
    "0-2": "\\< 12N",
    "0-3": "Yes",
    "1-0": "`encrypted_card`",
    "1-1": "This field must be sent with a value of \"true\" if the card number to be sent in the next step of the flow uses SiTef encryption. <br/> The option to send the encrypted card will only be available through routing via SiTef and prior SiTef setup is required.<br/> Options: <br/>1. **\"true\"** <br/>2. **\"false\"** (default)",
    "1-2": "\\< 5 AN",
    "1-3": "No",
    "2-0": "`merchant_usn`",
    "2-1": "Unique sequential id for each order created by the store. <br/> NSU will be used in all communication with the store to identify the order. As this is a store-side access key, although it is optional for Carat Portal, it is strongly recommended that the field be formatted and sent by the store application.",
    "2-2": "\\< 12 N",
    "2-3": "No",
    "3-0": "`order_id`",
    "3-1": "Order code to be displayed to the buyer, defined by the merchant. It should be different at each request to facilitate traceability. <br/> <FISERV noTags> If the store's integration with the acquirer/routing networks (Cielo, Redecard, etc) is via **SiTef** (TEF), the field **orderId**, which has a maximum length of 40 characters, will be shortened to 12 characters due to a **SiTef** restriction. This reduction will be performed by keeping the characters from left to right (eg if an order code entered is 12345678901234567890 in Carat Portal, in **SiTef** it will only be 123456789012). </FISERV>",
    "3-2": "<u>\\<</u> <FISERV noTags>40</FISERV><BIN noTags>20</BIN> AN",
    "3-3": "No",
    "4-0": "`transaction_type`",
    "4-1": "Fixed value \"preauthorization\"",
    "4-2": "= 15 A",
    "4-3": "Yes",
    "5-0": "`soft_descriptor`",
    "5-1": "Additional text that will be presented alongside the name of the establishment in the credit card invoice. [Learn more](./soft-descriptor.md)",
    "5-2": "<u>\\<</u> 22 AN",
    "5-3": "NO",
    "6-0": "`ecomm_pos_ref`",
    "6-1": "This field will send and identification that will appear in the PDV field of the SiTef Web report for e-commerce transactions.",
    "6-2": "<u>\\<</u> 8 AF",
    "6-3": "NO",
    "7-0": "`installment_type`",
    "7-1": "Installment financing type:<br/>Value 3 = installments with interest.<br/>Value 4 = installments without interest (use this value also on spot sales).<br/>Value 6 = installments with interest (IATA).<br/>Value 7 = installments without interest (IATA).<br/>The IATA financing types are only used by companies that work with air transportation.",
    "7-2": "<u>\\<</u> 2 N",
    "7-3": "YES",
    "8-0": "`installments`",
    "8-1": "Number of installments. Send `1` for spot sales.",
    "8-2": "<u>\\<</u> 2 N",
    "8-3": "YES",
    "9-0": "**iata**",
    "9-1": "This element contains specific fields for IATA transactions.",
    "9-2": "",
    "9-3": "",
    "10-0": "`departure_tax`",
    "10-1": "Departure tax in cents.",
    "10-2": "<u>\\<</u> 12 N",
    "10-3": "YES only for installment_type = 6 or 7",
    "11-0": "`first_installment`",
    "11-1": "Amount of the first installment on IATA transactions in cents. This functionality is available only for Getnet acquirer.",
    "11-2": "<u>\\<</u> 12 N",
    "11-3": "NO"
  },
  "cols": 4,
  "rows": 12,
  "align": [
    null,
    null,
    null,
    null
  ]
}
[/block]


</FISERV>

<BIN>

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Format",
    "h-3": "Mandatory",
    "0-0": "`amount`",
    "0-1": "Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas",
    "0-2": "\\< 12N",
    "0-3": "Yes",
    "1-0": "`encrypted_card`",
    "1-1": "This field must be sent with a value of \"true\" if the card number to be sent in the next step of the flow uses SiTef encryption. <br/> The option to send the encrypted card will only be available through routing via SiTef and prior SiTef setup is required.<br/> Options: <br/>1. **\"true\"** <br/>2. **\"false\"** (default)",
    "1-2": "\\< 5 AN",
    "1-3": "No",
    "2-0": "`merchant_usn`",
    "2-1": "Unique sequential id for each order created by the store. <br/> NSU will be used in all communication with the store to identify the order. As this is a store-side access key, although it is optional for Carat Portal, it is strongly recommended that the field be formatted and sent by the store application.",
    "2-2": "\\< 12 N",
    "2-3": "No",
    "3-0": "`order_id`",
    "3-1": "Order code to be displayed to the buyer, defined by the merchant. It should be different at each request to facilitate traceability. <br/> <FISERV noTags> If the store's integration with the acquirer/routing networks (Cielo, Redecard, etc) is via **SiTef** (TEF), the field **orderId**, which has a maximum length of 40 characters, will be shortened to 12 characters due to a **SiTef** restriction. This reduction will be performed by keeping the characters from left to right (eg if an order code entered is 12345678901234567890 in Carat Portal, in **SiTef** it will only be 123456789012). </FISERV>",
    "3-2": "<u>\\<</u> <FISERV noTags>40</FISERV><BIN noTags>20</BIN> AN",
    "3-3": "No",
    "4-0": "`transaction_type`",
    "4-1": "Fixed value \"preauthorization\"",
    "4-2": "= 15 A",
    "4-3": "Yes",
    "5-0": "`soft_descriptor`",
    "5-1": "Additional text that will be presented alongside the name of the establishment in the credit card invoice. [Learn more](./soft-descriptor.md)",
    "5-2": "<u>\\<</u> 22 AN",
    "5-3": "NO",
    "6-0": "`ecomm_pos_ref`",
    "6-1": "This field will send and identification that will appear in the PDV field of the SiTef Web report for e-commerce transactions.",
    "6-2": "<u>\\<</u> 8 AF",
    "6-3": "NO",
    "7-0": "`installment_type`",
    "7-1": "Installment financing type:<br/>Value 3 = installments with interest.<br/>Value 4 = installments without interest (use this value also on spot sales).<br/>Value 6 = installments with interest (IATA).<br/>Value 7 = installments without interest (IATA).<br/>The IATA financing types are only used by companies that work with air transportation.",
    "7-2": "<u>\\<</u> 2 N",
    "7-3": "YES",
    "8-0": "`installments`",
    "8-1": "Number of installments. Send `1` for spot sales.",
    "8-2": "<u>\\<</u> 2 N",
    "8-3": "YES",
    "9-0": "**iata**",
    "9-1": "This element contains specific fields for IATA transactions.",
    "9-2": "",
    "9-3": "",
    "10-0": "`departure_tax`",
    "10-1": "Departure tax in cents.",
    "10-2": "<u>\\<</u> 12 N",
    "10-3": "YES only for installment_type = 6 or 7"
  },
  "cols": 4,
  "rows": 11,
  "align": [
    null,
    null,
    null,
    null
  ]
}
[/block]


</BIN>

Format field caption:

A = alphanumeric

N = numeric

N A = not applied

## Response Parameters

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Format",
    "0-0": "`code`",
    "0-1": "Carat Portal response code. Any code other than **‘0’** means failure. For more information, see [Responde Codes](./codigos-da-api.md#response-codes).",
    "0-2": "\\< 4 N",
    "1-0": "`message`",
    "1-1": "Carat Portal's response message.",
    "1-2": "\\< 500 A",
    "2-0": "`amount`",
    "2-1": "Transaction's amount defined by the store (in cents) at transaction creation.",
    "2-2": "\\< 12 N",
    "3-0": "`merchant_usn`",
    "3-1": "Unique sequential number sent by store transaction creation.",
    "3-2": "\\< 12 N",
    "4-0": "`nit`",
    "4-1": "Pre-authorization transaction ID in Carat Portal.",
    "4-2": "= 64 A",
    "5-0": "`order_id`",
    "5-1": "Order code sent by store at transaction creation.",
    "5-2": "<u>\\<</u> <FISERV noTags>40</FISERV><BIN noTags>20</BIN> AN",
    "6-0": "`status`",
    "6-1": "Pre-authorization transaction status in Carat Portal.",
    "6-2": "= 3 A"
  },
  "cols": 3,
  "rows": 7,
  "align": [
    null,
    null,
    null
  ]
}
[/block]