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:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
Content-Type | Fixed value application/json | = 15 AN | YES |
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
idempotency_key | It's like a random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API. | < 80 N | YES |
Examples:#
Request:
Response:
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:
Response:
Request Parameters#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
amount | Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas | < 12N | Yes |
encrypted_card | 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. 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 AN | No |
merchant_usn | Unique 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 N | No |
order_id | Order 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 AN | Yes |
authorizer_id | Carat Portal authorizers ID. Learn more. | < 3 N | YES |
customer_id | Buyers' ID. Only alphanumerics are allowed (no dots, dashes or other special characters). | < 20 AN | NO |
discount | Discount 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 N | NO |
installments | Number of installments. Send 1 for spot sales. | < 2 N | YES |
installment_type | Installment 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 N | YES |
mcc | Merchant Category Code - Indicates the merchant category's ID. | < 4 N | It is optional to send it to acquirers with sub-merchant funding via SiTef. |
merchant_email | Merchant e-mail. When this parameter is sent, it overwrites the merchant registered e-mail. | < 40 AN | NO |
promo_code | Visa 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. | AN | NO |
soft_descriptor | Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more | < 22 AN | NO |
subtotal | Subtotal amount, in cents. In case of pre-authorizations with promotional amounts by using Visa Checkout, VISA recommends that this field be submitted additionally. | < 12 N | NO |
subacquirer_merchant_id | Merchant identification for the subacquirer. | < 22 N | NO |
| card | Sending card data is mandatory. Only one of these fields must be used: number, token or wallet_transaction_id | ||
holder | Cardholder's name. | < 30 AN | COND. |
number | Customer's card number (PAN). Brand generated token (DPAN) for network token payment. | < 19 N | |
cryptogram | Cryptogram generated by the card brand | = 28 AN | NO |
wallet_type | Field 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”. | AN | NO |
token | Used for recurring pre-authorizations, when the card is already stored at Carat Portal database. | = 88 AN | COND. |
wallet_transaction_id | Wallet Visa Checkout transaction ID. | < 25 AN | COND. |
initial_wallet_transaction_id | Informs 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 AN | COND. |
expiry_date | Card expiry date in MMYY format. | = 4 N | COND. |
security_code | Card security code. | < 5 N | COND. |
external_authentication | This element receives MPI authentication fields. | ||
version | 3DS version used in the authentication process (only version 2 is currently being accepted). | < 1 AN | NO |
eci | Eletronic Commerce Indicator – Card holder authentication security level indicator. | < 3 N | NO |
xid | External card holder authentication transaction id. | < 40 N | NO |
cavv | Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data. | < 40 N | NO |
acquirer | Data required only to specific acquirers / routings. | ||
terminal | Sitef terminal code. In absence Carat Portal will generate a random terminal code. | = 14 N | NO |
mid | Sitef terminal code. In absence Carat Portal will generate a random terminal code. | < 15 AN | COND. |
company_code | Sitef company code. In absence Carat Portal will use company code from merchant configuration. | = 8 N | NO |
additional_data | Element for sending additional data. | ||
ecomm_pos_ref | This field will send and identification that will appear in the PDV field of the SiTef Web report for e-commerce transactions. | < 8 AF | NO |
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
terminalecompany_codeparameters 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).
| Parameter | Description | Format |
|---|---|---|
code | Carat Portal response code. Anything besides 0 means failure. Learn more. | < 4 N |
message | Carat Portal response message. | < 500 AN |
pre_authorization | ||
acquirer_id | Acquirer/routing ID used in transaction. | < 4 N |
acquirer_name | Acquirer/routing name used in transaction. | < 100 AN |
amount | Purchase amount specified by merchant (in cents) on transaction creation. | < 12 AN |
authorization_number | Authorization number | < 6 AN |
authorizer_code | Authorizer responde code. | < 10 AN |
authorizer_date | Authorizer 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_id | Authorizer ID use in transaction. | < 4 N |
authorizer_merchant_id | Merchant ID from authorizer. | < 100 AN |
authorizer_message | Reponse message from authorizer. | < 500 AN |
customer_receipt | Customer receipt. | < 4000 AN |
eci | Eletronic Commerce Indicator (pre-authorization security level indicator on transactions). | < 3 AN |
esitef_usn | Carat Portal pre-authorization's unique sequential number. | = 15 N |
host_usn | Authorizer NSU. | < 15 AN |
issuer | Issuer code returned by the authorizer. | < 5 AN |
merchant_receipt | Merchant receipt. | < 4000 AN |
merchant_usn | Unique sequential number sent by merchant at the transaction creation. | < 12 AN |
nit | Carat Portal pre-authorization transaction ID. | = 64 AN |
order_id | Order ID sent by the merchant at transaction creation. | < 40 AN |
payment_type | Payment 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_usn | SiTef pre-authorization's unique sequential number. | = 6 N |
status | Carat Portal pre-authorization transaction status. | = 3 AN |
tid | Acquirer/routing transaction ID. This field is only returned in transactions with external acquirer's. | < 40 AN |
xid | XID field returned on 3DS authentications or certain acquirers/routings. | < 40 AN |
retryable_code | Reversibility 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 |