Pre-Authorization Effectuation service
Call details#
The nit obtained from the return of the pre-authorization creation service should be sent on the pre-authorization effectuation operation along with the parameters described in the table below (as necessary by each application):
- Resource:
/v1/preauthorizations/{nit} - 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 |
Examples:#
Request:
To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br
Pre-Authorization#
Request:
To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br
Response:
Pre-Authorization - Network Token#
Some card brands have a tokenization solution that offers the storage of cards in safes at the brand itself, in an encrypted form. This brand tokenization is intended to improve the security and quality of the transmitted card information, which leads to possible increases in the conversion of approval by issuing banks.
Request:
To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br
Response:
Request Parameters#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
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 suggests 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 | Required only when using sub-acquirer Stone WS and it is optional to send it to acquirers with sub-merchant funding via SiTef. |
merchant_email | Store e-mail. When this parameter is sent, it overwrites the store registered e-mail. | < 40 AN | NO |
nit | Transaction ID in Carat Portal (encrypted). Obtained from beginTransaction's return. | = 64 AN | YES |
promo_code | Visa Checkout promotion code used in pre-authorization. In case of pre-authorizations with promotional values when using Visa Checkout, VISA suggests 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 suggests that this field be submitted additionally. | < 12 N | NO |
subacquirer_merchant_id | It is the 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. Required only for e-Rede, GetNet WS e VR (SmartNet) routings. | < 30 AN | COND. |
number | Customer's card number (PAN). Brand generated token (DPAN) for network token payment. Learn more | < 19 N | |
cryptogram | Cryptogram generated by the card brand | = 28 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. |
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 |
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 |
company_code | Sitef company code. In absence Carat Portal will use company code from merchant configuration. | = 8 N | NO |
(\*) **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: 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 store 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 store (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. | < 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 store at the transaction creation. | < 12 AN |
nit | Carat Portal pre-authorization transaction ID. | = 64 AN |
order_id | Order ID sent by the store 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 store's transaction retry mechanism. Valid codes:01 – Reversible Denied Transaction, Retain Later.02 – Irreversible Denied Transaction, Non-Retentive. | = 2 N |