Pre-Authorization Creation

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.

Call details#

  • Resource: /v1/transactions
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Header parameters:
Content-TypeFixed value "application/json"= 15 AYes
merchant_idCarat Portal store's ID. Production and certification IDs are different.≤ 15 AYes
merchant_keyStore authentication key in Carat Portal. Production and certification keys are different.< 80 AYes


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



To use this example, don't forget to define the variable {{url}} to the value

--request POST "https://{{url}}/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"


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

Request Parameter#

amountTotal purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas< 12NYes
encrypted_cardThis 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.
The option to send the encrypted card will only be available through routing via SiTef and prior SiTef setup is required.
1. "true"
2. "false" (default)
< 5 ANNo
merchant_usnUnique sequential id for each order created by the store.
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.
< 12 NNo
order_idOrder code to be displayed to the buyer, defined by the merchant. It should be different at each request to facilitate traceability.
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).
< 40 ANNo
transaction_typeFixed value "preauthorization"= 15 AYes
soft_descriptorAdditional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more< 22 ANNO
ecomm_pos_refThis field will send and identification that will appear in the PDV field of the SiTef Web report for e-commerce transactions.< 8 AFNO
installment_typeInstallment financing type:
Value 3 = installments with interest.
Value 4 = installments without interest (use this value also on spot sales).
Value 6 = installments with interest (IATA).
Value 7 = installments without interest (IATA).
The IATA financing types are only used by companies that work with air transportation.
< 2 NYES
installmentsNumber of installments. Send 1 for spot sales.< 2 NYES
iataThis element contains specific fields for IATA transactions.
departure_taxDeparture tax in cents.< 12 NYES only for installment_type = 6 or 7
first_installmentAmount of the first installment on IATA transactions in cents. This functionality is available only for Getnet acquirer.< 12 NNO

Format field caption:

A = alphanumeric

N = numeric

N A = not applied

Response Parameters#

codeCarat Portal response code. Any code other than ‘0’ means failure. For more information, see Responde Codes.< 4 N
messageCarat Portal's response message.< 500 A
amountTransaction's amount defined by the store (in cents) at transaction creation.< 12 N
merchant_usnUnique sequential number sent by store transaction creation.< 12 N
nitPre-authorization transaction ID in Carat Portal.= 64 A
order_idOrder code sent by store at transaction creation.< 40 AN
statusPre-authorization transaction status in Carat Portal.= 3 A