Pre-Authorization with Idempotence

Pre-authorization interface that allows the merchant to perform pre-authorization requests in a single call.

Call Details#

  • Resource: /v2/preauthorizations/
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
Content-TypeFixed value application/json= 15 ANYES
merchant_idMerchant code on Carat Portal. The production and certification codes will be different.< 15 ANYES
merchant_keyMerchant authentication key on Carat Portal. The production and certification keys will be different.< 80 ANYES
idempotency_keyIt's like a random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API.< 80 NYES

Examples:#

Request:

curl
--request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "idempotency_key: ************"
--data-binary
{
"merchant_usn": "12050620649",
"order_id": "3232333",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "2220",
"card": {
"expiry_date": "1223",
"security_code": "123",
"number": "5555555555555555"
}
}

Response:

{
"code": "0",
"message": "OK. Transaction successful.",
"pre_authorization": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "2623a02dcdb6c30c8a243a993c16e983ec270d7dbaf66833e78cb54e610b4e39",
"order_id": "3232333",
"customer_receipt":"=== CUSTOMER RECEIPT ===",
"merchant_receipt":"=== MERCHANT RECEIPT ===",
"authorizer_id": "2",
"acquirer_id": "1005",
"acquirer_name": "Redecard",
"authorizer_date": "13/09/2023T11:42",
"authorization_number": "135858",
"merchant_usn": "12050620649",
"esitef_usn": "230913025438034",
"sitef_usn": "135858",
"host_usn": "999135858 ",
"amount": "2220",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000038",
"acquirer_cnpj": "67844256000156"
}
}

Pre-Authorization using the same idempotency_key with different order_id#

When a given request is sent with the same idempotency key, but with a different payload.

Request:

curl
--request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "idempotency_key: ************"
--data-binary
{
"merchant_usn": "12050620649",
"order_id": "32323333",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "2220",
"card": {
"expiry_date": "1223",
"security_code": "123",
"number": "5555555555555555"
}
}

Response:

{
"code": "1270",
"message": "Idempotent transaction body does not match the original",
"pre_authorization": {
"status": "INV",
"nit": "a9c6e0c275bf6eecb7deca20ab96dfd4733ae1a2f4eb6fd8139df1af876598da",
"order_id": "32323333",
"merchant_usn": "12050620649",
"esitef_usn": "230913025438024",
"amount": "2220"
}
}

Request Parameters#

ParameterDescriptionFormatMandatory
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.
Options:
1. "true"
2. "false" (default)
< 5 ANNo
merchant_usnUnique sequential id for each order created by the merchant.
NSU will be used in all communication with the merchant to identify the order. As this is a merchant-side access key, although it is optional for Carat Portal, it is strongly recommended that the field be formatted and sent by the merchant application.
< 12 NNo
order_idOrder code defined by the merchant. It's advised that it is different for each order so that it becomes easier to track it.
For transactions routed through the acquirer Bin, there's a 20 characters limit.
< 40 ANYes
authorizer_idCarat Portal authorizers ID. Learn more.< 3 NYES
customer_idBuyers' ID. Only alphanumerics are allowed (no dots, dashes or other special characters).< 20 ANNO
discountDiscount amount in cents. In case of pre-authorizations with promotional values when using Visa Checkout, VISA recommends that this field should be submitted additionally.< 12 NNO
installmentsNumber of installments. Send 1 for spot sales.< 2 NYES
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
mccMerchant Category Code - Indicates the merchant category's ID.< 4 N Required only when using sub-acquirer Stone WS and it is optional to send it to acquirers with sub-merchant funding via SiTef.
merchant_emailMerchant e-mail. When this parameter is sent, it overwrites the merchant registered e-mail.< 40 ANNO
promo_codeVisa Checkout promotion code used in pre-authorization. In case of pre-authorizations with promotional values when using Visa Checkout, VISA recommends that this field should be submitted additionally.ANNO
soft_descriptorAdditional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more< 22 ANNO
subtotalSubtotal amount, in cents. In case of pre-authorizations with promotional amounts by using Visa Checkout, VISA recommends that this field be submitted additionally.< 12 NNO
subacquirer_merchant_idMerchant identification for the subacquirer.< 22 NNO
cardSending card data is mandatory. Only one of these fields must be used: number, token or wallet_transaction_id
holderCardholder's name. Required only for e-Rede, GetNet WS e VR (SmartNet) routings. < 30 ANCOND.
numberCustomer's card number (PAN).

Brand generated token (DPAN) for network token payment.
< 19 N
cryptogramCryptogram generated by the card brand= 28 ANNO
wallet_typeField that specifies whether the transaction is processed with PAN or DPAN. If “type” is empty, the default value is PAN (non-tokenized card number). If there is a tokenized transaction, you must send the value “network_token”.ANNO
tokenUsed for recurring pre-authorizations, when the card is already stored at Carat Portal database.= 88 ANCOND.
wallet_transaction_idWallet Visa Checkout transaction ID.< 25 ANCOND.
initial_wallet_transaction_idInforms if the Wallet ID (wallet_transaction_id) is being used for the first time. If it's the first time, send true, otherwise, send false. Required only for Visa Checkout.
Default value: true
< 5 ANCOND.
expiry_dateCard expiry date in MMYY format.= 4 NCOND.
security_codeCard security code.< 5 NCOND.
external_authenticationThis element receives MPI authentication fields.
version3DS version used in the authentication process (only version 2 is currently being accepted).< 1 ANNO
eciEletronic Commerce Indicator – Card holder authentication security level indicator.< 3 NNO
xidExternal card holder authentication transaction id.< 40 NNO
cavvCardholder Authentication Verification Value - Codes that refers to card holder authentication result data.< 40 NNO
acquirerData required only to specific acquirers / routings.
terminalSitef terminal code. In absence Carat Portal will generate a random terminal code.= 14 NNO
midSitef terminal code. In absence Carat Portal will generate a random terminal code.< 15 ANCOND.
company_codeSitef company code. In absence Carat Portal will use company code from merchant configuration.= 8 NNO
additional_dataElement for sending additional data.
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

(*) Installments funding routed by GetNetLac via SiTef : In this case, the merchant will be responsible for the installment control, so the installment rules set up for the Carat Portal HTML payment interface won't take effect, only the authorizing installment rules will be verified and applied. For these mentioned networks, if pre-authorization is made at spot, the capture cannot be split. Also, pre-authorizations routed by GetNetLac via SiTef, when splitted, are only accepted without interest, that is, with the parameter installment_type = 4. Interest-free installments are not accepted on this routing.

WARNING:

In addition to the return parameters of the services described in this specification, Carat may return other parameters without prior notice.

It is important that the application is prepared to receive unknown parameters in addition to the parameters already specified and simply ignore them.

The terminal e company_code parameters must be used only for SiTef routings and must be sent simultaneously.
It is also necessary send a request to the Carat Portal Support Team for the permission Allows the sending of Company and SiTef Terminal through REST.

Response Parameters#

The table below contains the response parameters of the pre-authorization effectuation service. The app should merchant the parameters that finds necessary. We suggest storing the parameters:order_id, authorization_number, merchant_usn, esitef_usn, sitef_usn, host_usn, status, code, amount, message (the message parameter can be displayed to the customer).

ParameterDescriptionFormat
codeCarat Portal response code. Anything besides 0 means failure. Learn more.< 4 N
messageCarat Portal response message.< 500 AN
pre_authorization
acquirer_idAcquirer/routing ID used in transaction.< 4 N
acquirer_nameAcquirer/routing name used in transaction.< 100 AN
amountPurchase amount specified by merchant (in cents) on transaction creation.< 12 AN
authorization_numberAuthorization number< 6 AN
authorizer_codeAuthorizer responde code.< 10 AN
authorizer_dateAuthorizer pre-auth effectuation date, returned by the authorizer on the format DD/MM/AAAA’T’HH:mm. Example: 13/07/2017T16:03= 16 AN
authorizer_idAuthorizer ID use in transaction.< 4 N
authorizer_merchant_idMerchant ID from authorizer.< 100 AN
authorizer_messageReponse message from authorizer.< 500 AN
customer_receiptCustomer receipt.< 4000 AN
eciEletronic Commerce Indicator (pre-authorization security level indicator on transactions).< 3 AN
esitef_usnCarat Portal pre-authorization's unique sequential number.= 15 N
host_usnAuthorizer NSU.< 15 AN
issuerIssuer code returned by the authorizer.< 5 AN
merchant_receiptMerchant receipt.< 4000 AN
merchant_usnUnique sequential number sent by merchant at the transaction creation.< 12 AN
nitCarat Portal pre-authorization transaction ID.= 64 AN
order_idOrder ID sent by the merchant at transaction creation.< 40 AN
payment_typePayment type from the selected authorizer: B = boleto, C = credit, D = debit, P = Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = Boleto NR via Web Service= 1 AN
sitef_usnSiTef pre-authorization's unique sequential number.= 6 N
statusCarat Portal pre-authorization transaction status.= 3 AN
tidAcquirer/routing transaction ID. This field is only returned in transactions with external acquirer's.< 40 AN
xidXID field returned on 3DS authentications or certain acquirers/routings.< 40 AN
retryable_codeReversibility indicator of a transaction whose authorization was denied by the authorizer. This field will be returned in the response to the card payment request and must be taken into account in the online merchant's transaction retry mechanism. Valid codes:
01 – Reversible Denied Transaction, Retain Later.
02 – Irreversible Denied Transaction, Non-Retentive.
= 2 N