Pre-authorization
Overview#
Carat Portal is a multi-service payment gateway capable of processing credit card transactions, bank transfers, generating bills, integration with mobile payment options, among other services that can be easily added to the platform.
Online Payement has two interfaces for integration with the Virtual Store, HTML Interface and Web Services, enabling the proper way for the store to interact with Payment Online, depending on the language and execution platform of the virtual store.
The REST interface provides credit card payments, pre-authorization, pre-authorization capture and pre-paid mobile top up.
For payments via bank such as bank transfer, bank slip, use the HTML Interface; prepaid mobile top up is also available in the HTML Interface.
Certification Process#
The certification process of the application integrated to the Carat Portal will be carried out by the Authorizers/Carat Portal Support team. It is the customer's responsibility to inform Technical Support that the development of the application has been completed, so that the necessary steps can be taken to carry out the certification.
To do so, the customer must contact autores5317@softwareexpress.com.br
Only the application that successfully completes the Certification process will be able to go into production; Certification, therefore, is a mandatory process
Supported Routings#
Carat Portal pre-authorization functionality supports the following routes:
- Rede (via SiTef)
- Cielo (via SiTef)
- Amex (via SiTef)
- GetNetLac (via SiTef)
- Safra (via SiTef)
- Adiq (via SiTef)
- BIN (via SiTef)
- Sipag (via SiTef)
- iCards (via SiTef)
- e-Rede
- GetNet WS
- GlobalPayments WS
- Cielo e-Commerce
- Stone WS
- EPX
Required Carat Portal Settings#
The use of the Pre-Authorization functionality must always have your permission enabled by the Support teams (Certification environment) and Production (Production environment).
Integration of Pre-Authorization, Pre-Authorization Capture and Cancellation via REST Web Service#
The purpose of this document is to describe the pre-authorization interface via REST where the collection of parameters will be carried out by the Virtual Store and the Carat Portal will only carry out the transaction with the network acquirer/routing.
Pre-authorization is a transaction whose value will be set aside from the card limit, but will not be debited immediately, and may be captured later for an amount equal to or less than the authorized amount. The deadline to perform the capture, as well as the possibility of capturing smaller values will depend on the negotiation with the acquirer/routing network, it will be up to the Virtual Store to consult the acquirer/routing network.
The pre-authorization cancellation can be done to make available again the reserved amount of the card limit, in case the pre-authorization capture is not performed.
Upon completion of the pre-authorization capture transaction, it can also be reversed. For more details on cancellation and reversal, see the Payment's Interface Web Service REST, Scheduling and Cancellation must be consulted. If the merchant does not have this in hand, he must ask the Payment Online service teams.
Flow of Pre-Authorization, Capture and Status Inquiry#
The pre-authorization flow will be started by the Virtual Store when the application sends the beginTransaction operation (Figure 1), in the request response, the application will receive the nit (transaction identifier) and other parameters (Table two). The nit received in beginTransaction along with other parameters (Table 3), will be sent by the Virtual Store in the doPreAuthorization operation and must handle the parameters received in the response to the beginTransaction request. Later (according to the business rule) the same nit sent in the pre-authorization must be sent in the capture operation together with other parameters (Table 9) and must handle the parameters received in the webservice response.
If there is a failure in receiving the webservice response (ie, timeout) from doPreAuthorization or capture, the store application mandatory must perform the status query with the getStatus operation, to verify the result of the transaction.
In case the application does not receive the beginTransaction operation response, it will not be necessary to perform the getStatus operation, just that the application performs the beginTransaction again. Because right now, still the transaction that will compromise the limit or the charge on the customer's card bill was not sent.
The status query (getStatus) is extremely important to avoid an undue charge (possible double billing or billing without receipt of the product/service) on the customer's invoice. The figures below illustrate the flows:
Pre-Authorization#
All communication will be carried out via HTTPS/TLS, and it is important that the merchant's server supports encryption with at least 128 bits and minimum TLS 1.2 protocol. The Virtual Store application server will make the call on the address for pre-authorization via Web Service, as described below, according to the environment in question.
Certification/Testing Environment URL:
https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/
Production environment URL:
https://esitef-ec.softwareexpress.com.br/e-sitef/api/
Attention: Never use the IP instead of the esitef-ec.softwareexpress.com.br domain, because the IP can change at any time and without notice, so it is mportant to use the domain to access the Onlyne Payment.
Web Service has the following operations: beginTransaction, doPreAuthorization, capture, doCardQuery and getStatus
Other operations may be included without prior notice.
Important: In addition to the webservice response parameters described in this specification, the Carat Portal may return other parameters without prior notice. IT'S important that the application is prepared to receive extra parameters in addition to the already specified parameters and simply discard them.
beginTransaction operation – transaction creation#
beginTransaction operation request parameters#
The Pre-Authorization transaction flow is started consuming the beginTransaction operation, which will generate a registration in Carat Portal of a transaction with status = NOV, and the nit parameter will return to the application, which will identify that transaction.
nit has a usage period configured in Carat Portal, if this time limit exceeds the transaction will pass from status “NOV” to status “EXP”. In this case, the use of the same nit will no longer be allowed, if necessary consume the beginTransaction operation again to generate another valid nit.
The beginTransaction operation must be sent with the parameters in the table below.
- Resources: /v1/transactions
- Operation HTTP: POST
- requisition format:
JSON - response format: JSON
- header parameters:
| Parameter Name | Description | Size | Mandatory |
|---|---|---|---|
| Content-Type | Fixed value "application/json" | = 15 A | Yes |
merchant_id | Store code in the Carat Portal. The production and certification codes will be different | ≤ 15 A | Yes |
merchant_key | Store's Authentication key for the Carat Portal. The production and certification keys will be different. | < 80 A | yes |
| Parameter Name | Description | Size | Mandatory | | - | - | - | - | | amount | Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send the value without the comma and period | < 12N | Yes | | encrypted_card | This field must be sent with a “true” value 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 possible with routing via SiTef and prior configuration of the SiTef in question is necessary.
Options:
1. **“true”**
2. **“false”** (default value) | < 5 AN | No | | merchant_usn | Unique sequential number for each order, created by the store.
The NSU will be used in all communication with the store, in order to identify the order. As this is a possible key for store-side access, although it is optional for Carat Portal, it is strongly recommended that the field be formatted and sent by the store application. < 12 N | No | | order_id |Order code to be displayed to the buyer, defined by the merchant. It is recommended that it be different for each order to facilitate traceability.
If the integration of the Store with the acquiring/routing networks (Cielo, Redecard, etc) is via **SiTef** (TEF), the field * *orderId** which has a maximum length of 40 characters, will be reduced to 12 characters, due to a **SiTef** restriction. This reduction will be carried out keeping the characters from left to right (ex.: if an order code entered is 12345678901234567890 in Carat Portal, in **SiTef** it will be only 123456789012).| ≤ 40 A | No | | transaction_type | Fixed value “preauthorization” | = 15 A | Yes|
Caption of the "Size" field type:
A = alphanumeric
N = numeric
N A = not used
BeginTransaction Operation Response Parameters#
The table below shows the response parameters of the beginTransaction operation:
| Nome do Parâmetro | Descrição | Tamanho |
|---|---|---|
| code | Carat Portal response code. Any code other than ‘0’ means failure. For more information, see the document "Annex A-2 - Response Codes". | < 4 N |
| message | Carat Portal reply message. | < 500 A |
| amount | Transaction value specified by store (in cents) at transaction creation. | < 12 N |
| merchant_usn | Unique sequential number sent by the store when creating the transaction | < 12 N |
| nit | Identifier of the pre-authorization transaction in Carat Portal. | = 64 A |
| order_id | Order code sent by store at transaction creation | < 40 A |
| status | Status of pre-authorization transaction in Carat Portal. | = 3 A |
Request Example
Answer Example
doPreAuthorization operation - effecting pre-authorization#
The nit obtained in the return of the beginTransaction operation must be sent in the doPreAuthorization operation along with the parameters described in the table below (according to the need for each application):
- Resource: /v1/preauthorizations/{nit}
- Method HTTP: POST
- requisition format: JSON
- response format: JSON
- header parameters:
| Parameter Name | Description | Size | Mandatory |
|---|---|---|---|
| Content-Type | Fixed value “application/json” | = 15 A | yes |
| merchant_id | Store code in the Carat Portal. The production and certification codes will be different | ≤ 15 A | yes |
| merchant_key | Authentication key for the Carat Portal store. The production and certification keys will be different. | < 80 A | yes |
Requisition parameters of the doPreAuthorization operation
| Parameter name | Description | Size | Mandatory |
|---|---|---|---|
| authorizer_id | Authorizer code in the Carat Portal. See document Annex A – Authorizing Carat Portals. | ≤ 3 N | Yes |
| customer_id | Customer's personal document. Use only alphanumeric characters (no dots, dashes, or other special characters). | ≤ 20 A | No |
| discount | Discount amount, in cents. In case of pre-authorizations with promotional values for the use of Visa Checkout, VISA suggests that this field be sent additionally. | N | No |
| installments | Together with the installmenttype field, it indicates installment (**), used _ONLY with routed authorizers, e-Rede, GetNetLac via SiTef, Rede via SiTef and iCards via SiTef. Submit ‘1’ for cash transactions. | < 2 N | Conditional |
| installment_type | Together with the installments field, it indicates installments (), used ONLY with authorizers routed via e-Rede, GetNetLac via SiTef, Rede via SiTef and iCards via SiTef. For the other routes, the installment is only possible in capture. The possible values for the installment_type are: 3: Installment with interest from the credit card company 4**: Installment carried out by the store and without interest (adopt this value as default/ default for spot transactions) | = 1 N | Conditional |
| mcc | Merchant Category Code - Indicates the store's category code. Required when using Stone WS subacquiring. | < 4 N | Required only for Stone WS subpurchase |
| merchant_email | Store email. This parameter, when sent, overwrites the Store registration email. | ≤ 40 A | Optional |
| nit | Transaction identifier in the Carat Portal (encrypted). Retrieved from callback to beginTransaction. | = 64 A | Yes |
| promo_code | Visa Checkout promotion code used in pre-authorization. In case of pre-authorizations with promotional values for the use of Visa Checkout, VISA suggests that this field be sent additionally. | A | No |
| soft_descriptor | Additional text that will appear with the name of the store on the buyer's credit card statement. functionality only available for e-Rede and Bin acquiring networks/routings via SiTef. | ≤ 30 A | No |
| subtotal | Subtotal amount, in cents. In case of pre-authorizations with promotional values for the use of Visa Checkout, VISA suggests that this field be sent additionally. | N | No |
| expiry_date | Card expiration date in MMYY format. | = 4 N | Yes |
| holder | Cardholder's name. Required only for e-Rede, GetNet WS and VR (SmartNet) routings. | ≤ 30 A | Conditional |
| security_code | Security code. | ≤ 5 N | Yes |
| number (*) | Customer's card number (PAN). Mandatory to use one of the fields (number, token or initial_wallet_transaction_id) | ≤ 19 N | Yes |
| token (*) | Used for recurring pre-authorization cases, where the card must already be stored in the PayPal online database. | = 88 A | Conditional |
| wallet_transaction_id(*) | Transaction identification code with Visa Checkout wallet. About the use of Visa Checkout, please see document Attachment M-1 - VisaCheckout via WS | < 25 A | Conditional |
| initial_wallet_transaction_id | Informs if the Wallet ID (WALLET_TRANSACTION_ID) is being used for the first time. If it is the first time, send true, otherwise, send false. Possible values: true/false Default value:true | < 5 A | Required for Visa Checkout only |
(*) Mandatory use only one between fields: number, token or initial_wallet_transaction_id
() Installment routed by GetNetLac via SiTef: In this case, the store will be responsible for controlling the installments, therefore the installment rules configured for the payment interface will not come into effect Payment Online HTML, only the authorizing company's installment rules will be verified and applied. For these mentioned networks, if the pre-authorization is made in cash, the capture cannot be made in installments. Still, pre-authorizations routed by GetNetLac via SiTef, when paid in installments, are only accepted without interest, that is, with the installment_type parameter = 4**. Interest-free installments are not accepted for this routing.
DoPreAuthorization Operation Response Parameters#
The table below contains the response parameters of the doPreAuthorization operation. The application should store the parameters it deems 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 Name | Description | Size |
|---|---|---|
| code | Carat Portal response code. Any code other than "0" means failure. For more information, see document Annex A-2 - Response Codes. | < 4 N |
| message | Carat Portal reply message. | < 500 AN |
| acquirer_id | Acquirer/routing code used in transaction. | < 4 N |
| acquirer_name | Name of the acquirer/routing used in the transaction. | < 100 AN |
| amount | Purchase value specified by store (in cents) at transaction creation. | < 12 AN |
| authorization_number | Authorization number. | < 6 AN |
| authorizer_code | Authorizer response code. | < 10 AN |
| authorizer_date | Effective date of pre-authorization returned by the authorizer in DD/MM/YYYY’T’HH:mm format. Example: 07/13/2017T16:03 | = 16 D |
| authorizer_id | Authorization code used in the transaction. | < 4 N |
| authorizer_merchant_id | Merchant affiliation code with the authorizing agency. | < 100 AN |
| authorizer_message | Authorizer reply message. | < 500 AN |
| customer_receipt | Receipt(customer copy). | < 4000 AN |
| eci | Eletronic Commerce Indicator(indicator of the security level of the pre-authorization transaction via Cielo e-Commerce | |
| ). | < 3 AN | |
| esitef_usn | Unique sequential number of the pre-authorization transaction in Carat Portal. | = 15 N |
| host_usn | Authorizer's USN. | < 15 AN |
| issuer | Credit Card Company code returned by the aurhorizers | < 5 AN |
| merchant_receipt | Receipt (store's copy). | < 4000 AN |
| merchant_usn | Unique sequential number sent by the store when creating the transaction. | < 12 AN |
| nit | Identifier of the pre-authorization transaction in Carat Portal. | = 64 AN |
| order_id | Order code sent by store at transaction creation. | < 40 AN |
| payment_type | Type of payment of the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other means and payments, W = bank slip NR via Web Service | = 1 A |
| sitef_usn | Unique sequential number of the pre-authorization transaction in SiTef. | = 6 N |
| status | Carat Portal Pre-Authorization Transaction Status. | = 3 AN |
| tid | Transaction ID in acquirer/routing. This field is only returned in transactions with acquirers external to SiTef. | < 40 AN |
| xid | XID field returned in 3DS authentications or certain acquirers/routes. | < 40 AN |
Example request#
Example Answer#
Requisition parameters of the doPreAuthorization operation
For GetNetLac via SiTef routing it is possible to change the value of an uncaptured pre-authorization. To use this functionality, just call the doPreAuthorization operation again with the data of a pre-authorization transaction with CON status (confirmed) with addition of amount field. Below are the details of that call.
| Parameter Name | Description | Size | Required |
|---|---|---|---|
| nit | Transaction identifier in the Carat Portal. Obtained on callback to beginTransaction. | = 64 A | Yes |
| authorizer_id | Authorizer code in the Carat Portal. See document Annex A - Authorizing Carat Portal. | ≤ 3 N | Yes |
| amount | Total purchase amount (in cents). | ≤ 12 N | Yes |
| number | customer's card number (PAN). | ≤ 19 N | Yes |
| token | Used for recurring payment cases, where the card must already be stored in the Carat Portal database. Mandatory to use one of the fields (number, token or initial_wallet_transaction_id) | = 88 A | Conditional |
| expiry_date | Expiration date in MMYY format. | = 4 N | Yes |
| security_code | Security code. | ≤ 5 N | Yes |
The response fields are the same as for the doPreAuthorization operation, described in Table 6.
In case of success, the responseCode ‘0’ will be returned. The transaction status will not change in hypothesis any (success or failure). However, the sitef_usn, host_usn, authorization_number, sitef_date, fields customer_receipt and merchant_receipt will change if the change is confirmed.
Operation capture – pre-authorization capture#
The capture of Pre-Authorization aims to carry out the Pre-Authorization, which can be in the full amount or less than the total amount of the Pre-Authorization. This will depend on the business rule of the Virtual Store application.
The flow would be, perform the doPreAuthorization operation and if the result is approved, the capture operation should be consumed to complete the flow. The capture will be performed at the time defined by the business rules of the application.
In the capture operation, the amount parameter can have a value equal to or less than the value of the amount parameter of the pre-authorization.
For GetNetLac via SiTef routing, the installment can also be done in the pre-authorization step and in this case, the capture must receive a number of installments equal to or greater than that sent previously. Case to pre-authorization is made in cash, the capture cannot be made in installments.
In case of HTML pre-authorization transaction capture, installments and financing type follow obligatorily the values defined in the pre-authorization. So in this case there is no possibility of change of these values at the time of capture.
Call Details#
Resource: /v1/preauthorizations/capture/{nit}
HTTP Method: POST
requisition format: JSON
Reply Formata: JSON
header parameters:
| Parameter Name | Description | Size | Required |
|---|---|---|---|
| Content-Type | Fixed value “application/json” | = 15 A | Yes |
| merchant_id | Store code in the Carat Portal. Production and certification codes will be different | ≤ 15 A | Yes |
| merchant_key | Authentication key for the Carat Portal store. The production and certification keys will be different. | < 80 A | Yes |
Request parameters of Operation capture#
| Parameter Name | Description | Size | Required |
|---|---|---|---|
| amount | Total purchase amount (in cents). | ≤ 12 N | Yes |
| discount | Discount amount, in cents. In case of pre-authorizations with promotional values for the use of Visa Checkout, VISA suggests that this field be sent additionally. | N | No |
| installments (*) | Number of installments, 1 = in cash | ≤ 2 N | Yes |
| installment_type | Along with the installments field, it indicates installments. The possible values for installment_type are: 3: Installment with interest from the card company 4: Installment carried out by the store and without interest (adopt this value as default/default for cash transactions) | = 1 N | Yes |
| promo_code | Visa Checkout promotion code used in pre-authorization. In case of pre-authorizations with promotional values for the use of Visa Checkout, VISA suggests that this field be sent additionally. | A | Not |
| subtotal | Subtotal amount, in cents. In case of pre-authorizations with promotional values for the use of Visa Checkout, VISA suggests that this field be sent additionally. | N | No |
| number (**) | Customer's Card Number (PAN). | ≤ 19 N | Yes |
| token (**) | Used for recurring pre-authorization cases, where the card must already be stored in the Carat Portal database. | = 88 A | Conditional |
| wallet_transaction_id (**) | Transaction identification code with VisaCheckout wallet. | < 25 A | Required for Visa Checkout only |
| initial_wallet_transaction_id | Informs if the Wallet ID (WALLET_TRANSACTION_ID) is being used for the first time. If it is the first time, send true, otherwise, send false. Possible values: true/false Default value: true | < 5 A | Required for Visa Checkout only |
| acquirer.submerchant_split[] | It consists of an array for split payments, exclusive to BIN and Sipag routing, both via SiTef. Allows the division of parts of the total payment amount among other companies. The maximum number of items allowed in this array is 5 items. Each item is composed of the submechant_code and submerchant_amount fields. | No | |
| submerchant_code | BIN/Sipag establishment code | ≤ 15 AN | No |
| submerchant_amount | transaction value for the store | ≤ 12 N | No |
(*) installments: The maximum number of installments configured in the merchant's Carat Portal portal will not be verified in this field, serving only for HTML payments.
() Mandatory use only one** among the fields: number, token or initial_wallet_transaction_id
Capture Operation's response parameters#
| Parameter Name | Description | Size |
|---|---|---|
| code | Carat Portal response code. Any code other than "0" means failure. For more information, see attached document A-2 - Response Codes. | < 4 N |
| message | Carat Portal reply message. | < 500 AN |
| acquirer_id | Acquirer/routing code used in transaction. | < 4 N |
| acquirer_name | Name of acquirer/routing used in transaction. | < 100 AN |
| amount | Purchase amount specified by store (in cents) at transaction creation. | < 12 AN |
| authorization_number | Authorization number. | < 6 AN |
| authorizer_code | Authorizer response code. | < 10 AN |
| authorizer_date | Effective date of pre-authorization returned by the authorizer in DD/MM/YYYY’T’HH:mm format. Example: 07/13/2017T16:03 | = 16 D |
| authorizer_id | Code of the authorizer used in the transaction. | < 4 N |
| authorizer_merchant_id | Merchant affiliation code at the authorizing agency. | < 100 AN |
| authorizer_message | Authorizer reply message. | < 500 AN |
| customer_receipt | Coupon (via customer). | < 4000 AN |
| eci | Electronic Commerce Indicator (indicator of the security level of the pre-authorization transaction via Cielo e-Commerce). | < 3 AN |
| esitef_usn | Unique sequential number of the pre-authorization transaction in Carat Portal. | = 15 N |
| host_usn | Authorizer NSU. | < 15 AN |
| issuer | Flag code returned by the authorizer. | < 5 AN |
| merchant_receipt | Coupon (via establishment). | < 4000 AN |
| merchant_usn | Unique sequential number sent by the store when creating the transaction. | < 12 AN |
| nit | Identifier of the pre-authorization transaction in Carat Portal. | = 64 AN |
| payment_type | Type of payment of the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = bank slip NR via Web Service | = 1 A |
| sitef_usn | Unique sequential number of the pre-authorization transaction in SiTef. | = 6 N |
| status | Carat Portal Pre-Authorization Transaction Status. | = 3 AN |
| tid | Transaction ID in acquirer/routing. This field is only returned in transactions with acquirers external to SiTef. | < 40 AN |
| xid | XID field returned in 3DS authentications or certain acquirers/routes. | < 40 AN |
Request Exemple#
Answer Exemple#
doCardQuery operation - card query#
From a pre-authorization NIT with NOV (new) status, it is possible to query the card's BIN (first six digits) in SiTef to obtain data on its capabilities (possibility of payment in installments, maximum installments, security code requirement, etc.), or even know which store's authorizer is the most suitable for making the payment.
In the case of Visa Checkout transactions, this service will also return card and user data returned by Visa.
Flow#
Description of the flow:
- The merchant creates a transaction in Carat Portal, passing information such as store code, number of installments and order code and gets an NIT (Transaction Identifier Number) in response.
- The merchant sends the NIT obtained in the previous step and the card data to be consulted. With that, the Carat Portal returns data about the capabilities of the card sent.
- The virtual store then proceeds to consume the payment processing service, passing the NIT and the buyer's card details. On success, the payment transaction will change its status to CON (confirmed).
Call Details#
Resources: /v1/preauthorizations/{nit}/cards
Method HTTP: POST
Note: despite being a query, the POST method was chosen for security reasons.
-Request Format: JSON
Response format: JSON
Header parameters:
| Parameter Name | Description | Type | Size | Required |
|---|---|---|---|---|
| merchant_id | Store code in the Carat Portal. The production and certification codes will be different. | AN | ≤ 15 | YES |
| merchant_key | Authentication key for the Carat Portal store. The production and certification keys will be different. | AN | ≤ 80 | YES |
| Content-Type | It must be sent with the value “application/json”. | AN | = 15 | YES |
Example of Card Inquiry with Authorization Sending#
Request:
Answer:
Example of Card Inquiry without sending authorizer#
Request:
Answer:
Visa Checkout Card Inquiry Example#
Request:
Answer:
Example of Card Query with additional data for iCards routing via SiTef
Request:
Answer:
Request parameters
In the table below, there is a description of the request parameters for the card lookup service:
| Parameter Name | Description | Type | Size | Required |
|---|---|---|---|---|
| authorizer_id | Code of the authorizer in the Carat Portal, as listed in the document “Annex A – Carat Portal Authorizers”. This field is only mandatory if the “wallet_transaction_id” field is sent. | N | ≤ 3 | NO |
| number | Buyer's Card Number (PAN). | N | ≤ 19 | NO |
| token | HASH of a card stored in Pagamento Online. It is not allowed to send an open card number (campnumber’ field) and a stored card (‘token’ field) in the same request. | AN | = 88 | NO |
| wallet_transaction_id | ID of a digital wallet transaction. For now, this functionality is only available to the Visa Checkout authorizer (authorizer_id:406). It is not allowed to send an open card number (campnumber’ field), a stored card (‘token’ field) and a wallet_transaction_id in the same request. | AN | ≤ 25 | NO |
Note: Although not mandatory, it is recommended to send the authorizer_id for the card query, mainly for routing via SiTef, in order to have more effective behavior in relation to the routing registered to the authorizing company.
Response Parameters
On success, the HTTP response code will be 200. Any other code should be interpreted as an error. In the table below is the description of the response parameters of the card lookup service:
| Parameter Name | Description | Type | Size |
|---|---|---|---|
| code | Carat Portal response code. Any code other than '0' means failure. For more information, see the document “Annex A-2 – Response Codes”. | N | ≤ 4 |
| message | Carat Portal reply message. | AN | ≤ 500 |
| status | Status of pre-authorization transaction in Carat Portal. For more information, see 11.1. | AN | = 3 |
| authorizer_code | Authorizer response code. | AN | ≤ 10 |
| authorizer_message | Authorizer reply message. | AN | ≤ 500 |
| acquirer_name | Routing name. E.g.: Cielo | AN | ≤ 256 |
| authorizer_id | Authorizer code (use this ID when making payment). | N | ≤ 3 |
| is_customer_id_required | Indicates the mandatory collection of the customer's document. | T/F | ≤ 5 |
| is_expiry_date_required | Indicates the obligation to collect the expiration date of the buyer's card. | T/F | ≤ 5 |
| is_installment_funding_enabled | Indicates if payment is enabled. | T/F | ≤ 5 |
| is_security_code_required | Indicates mandatory security code collection. | T/F | ≤ 5 |
| is_spot_sale_enabled | Indicates whether cash payment is enabled. | T/F | ≤ 5 |
| is_with_interest_sale_enabled | Indicates whether interest payment is enabled. | T/F | ≤ 5 |
| is_without_interest_sale_enabled | Indicates whether interest-free payment is enabled. | T/F | ≤ 5 |
| max_installments_with_interest | Maximum installment with interest. | N | ≤ 2 |
| min_installments_with_interest | Minimum installment with interest. | N | ≤ 2 |
| visa_checkout_date | Object with data returned by Visa Checkout. | ||
| financing_plan_list | Object consisting of an array of financing plans presented in Via Certa Financiadora routing. A financing plan consists of the following fields: - cod_plano: identification code of the financing plan, which must be sent at the time of payment; - plan_type: financing plan type code;- desc_plan: plan description, which can be presented to the buyer; - parc_plano: maximum number of possible installments for the plan. | ||
| is_customer_postal_code_required | Indicates the mandatory collection of the user's postal code (zip code in Brazil). | T/F | < 5 |
| Key | Prefix name. | AN | ≤ 1024 |
| value | Prefix value | AN | ≤ 1024 |
Pre-authorization and capture cancellation#
If the pre-authorization transaction was carried out successfully and the Virtual Store does not want to carry out the capture, it can cancel the pre-authorization, releasing the reserved amount from the card limit to the customer. If the capture does not take place, after a certain period of time, the pre-authorization is automatically canceled, but the customer may want the pre-authorization to be canceled before, in order to release the amount of their card limit.
It is important to know that only one pre-authorization not captured transaction can be canceled in later days. A capture transaction can only be canceled on the same day it was made.
To cancel pre-authorization or pre-authorization capture, the flow is slightly different, in that the creation of the cancellation transaction returns the nit in the Authenticity URL, that is, the call to the beginCancelTransaction operation will simply return an “OK” and the nit will be returned in the previously registered Authenticity URL.
Note that the Carat Portal will only send the message "OK" if the NIT sending was successful, with the store server responding "HTTP 200 OK" and only after the "HTTP 200 OK" return that the nit da Cancellation transaction may be used.
Information for the development of the cancellation transaction including hash, see the manual REST Payment, Scheduling and Cancellation Web Service Interface. If you have not yet received the document, ask the e-mail autoridadores5317@softwareexpress.com.br or via tel. (11)3170-5317.
getStatus operation – transaction query#
In case of communication failure or excessive delay in the response (timeout) in any of the operations subsequent to beginTransaction, the store must compulsorily consume the getStatus operation. This operation allows you to check the status of a request to which the merchant did not get the answer, recovering the parameters that he could not receive in the normal flow.
The store must retrieve the transaction status (with a maximum period of 15 days for consultation) as long as it has the nit, through the webservice getStatus, passing as parameter the store authentication key (merchantKey) and the nit .
Development/Certification: in case you have not received the merchantKey for development/certification, please request it via e-mail autoristares5317@softwareexpress.com.br or by telephone (11) 3170-5317.
Production: the merchantKey for Production will be sent by the Production Carat Portal team, if it has not been received after the due procedures for entry into Production, please request to esitef.prod6773@softwareexpress. com.br.
Note that in exceptional cases the authentication key (merchantKey) can be changed for security reasons, however the production team will contact the store before the change.
Bearing in mind that several factors can cause a delay in the response, including internet instability and the host of the card authorizing network. We recommend that the store server has set the timeout equal to or greater than 90 seconds.
Note: This service will only return data if the transaction was made via Web Services, it will not work in case of transactions via HTML Interface.
Attention: The transaction query in the Carat Portal DOES NOT query the status of the transaction in the acquirer / authorizer. This service returns the status of the transaction in the Carat Portal database.
Example: If a pre-authorization transaction is confirmed in Pagamento Online, but is reversed via telephone directly to the acquirer / authorizer, this reversal will not necessarily be reflected in the payment consultation service of Pagamento Online.
Call Details#
Resource: /v1/transactions/{nit}
HTTP Method: GET
Request Format: JSON
Answer Format: JSON
Header parameters:
| Parameter Name | Description | Size | Required |
|---|---|---|---|
| Content-Type | Fixed value “application/json” | = 15 A | Yes |
| merchant_id | Store code in the Carat Portal. Production and certification codes will be different | ||
| merchant_key | Authentication key for the Carat Portal store. The production and certification keys will be different. | ≤ 80 A | Yes |
| nit | Transaction identifier in the Carat Portal. Got on callback to beginTransaction. | = 64 A | Yes |
Parameters of the getStatus operation request
The nit must be sent in the resource URL
| Parameter Name | Description | Size | Required |
|---|---|---|---|
| nit | Transaction identifier in the Carat Portal. Got on callback to beginTransaction. | = 64 A | Yes |
Calling the transaction query operation – getStatus – does not need a request body.
Parameters of the getStatus operation response
| Parameter Name | Description | Size |
|---|---|---|
| code | Carat Portal response code. Any code other than "0" means the query failed. For more information, see the document Annex A-2 - Response Codes. | < 4 N |
| message | Carat Portal response message from the query. | < 500 AN |
| acquirer_id | Acquirer/routing code used in transaction. | < 4 N |
| acquirer_name | Name of acquirer/routing used in transaction. | < 100 AN |
| amount | Purchase amount specified by store (in cents) at transaction creation. | < 12 AN |
| authorization_number | Authorization number. | < 6 AN |
| authorizer_code | Authorizer response code. | < 10 AN |
| authorizer_date | Effective date of pre-authorization returned by the authorizer in DD/MM/YYYY’T’HH:mm. | |
| Example: 07/13/2017T16:03 | = 16 D | |
| authorizer_id | Code of the authorizer used in the transaction. | < 4 N |
| authorizer_merchant_id | Merchant affiliation code at the authorizing agency. | < 100 AN |
| authorizer_message | Authorizer reply message. | < 500 AN |
| customer_receipt | Coupon (via customer). | < 4000 AN |
| eci | Electronic Commerce Indicator (indicator of the security level of the pre-authorization transaction via Cielo e-Commerce). | < 3 AN |
| esitef_usn | Unique sequential number of the pre-authorization transaction in Carat Portal. | = 15 N |
| host_usn | Authorizer NSU. | < 15 AN |
| issuer | Flag code returned by the authorizer. | < 5 AN |
| merchant_receipt | Coupon (via establishment). | < 4000 AN |
| merchant_usn | Unique sequential number sent by the store when creating the transaction. | < 12 AN |
| nit | Identifier of the pre-authorization transaction in Carat Portal. | = 64 AN |
| order_id | Order code sent by store at transaction creation. | < 40 AN |
| payment_type | Type of payment of the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = NR Bill via Web Service | = 1 A |
| sitef_usn | Unique sequential number of the pre-authorization transaction in SiTef. | = 6 N |
| status | Carat Portal Pre-Authorization Transaction Status. | = 3 AN |
| tid | Transaction ID in acquirer/routing. This field is only returned in transactions with acquirers external to SiTef. | < 40 AN |
| xid | XID field returned in 3DS authentications or certain acquirers/routes. | < 40 AN |
| acquirer_id | Acquirer/routing code used in transaction. | < 4 N |
| acquirer_name | Name of acquirer/routing used in transaction. | < 100 AN |
| amount | Purchase amount specified by store (in cents) at transaction creation. | < 12 AN |
| authorization_number | Authorization number. | < 6 AN |
| authorizer_code | Authorizer response code. | < 10 AN |
| authorizer_date | Effective date of pre-authorization returned by the authorizer in DD/MM/YYYY’T’HH:mm format. Example: 07/13/2017T16:03 | = 16 D |
| authorizer_id | Code of the authorizer used in the transaction. | < 4 N |
| authorizer_merchant_id | Merchant affiliation code at the authorizing agency. | < 100 AN |
| authorizer_message | Authorizer reply message. | < 500 AN |
| customer_receipt | Coupon (via customer). | < 4000 AN |
| eci | Electronic Commerce Indicator (indicator of the security level of the pre-authorization transaction via Cielo e-Commerce). | < 3 AN |
| esitef_usn | Unique sequential number of the pre-authorization transaction in Carat Portal. | = 15 N |
| host_usn | Authorizer NSU. | < 15 AN |
| issuer | Flag code returned by the authorizer. | < 5 AN |
| merchant_receipt | Coupon (via establishment). | < 4000 AN |
| merchant_usn | Unique sequential number sent by the store when creating the transaction. | < 12 AN |
| nit | Identifier of the pre-authorization transaction in Carat Portal. | = 64 AN |
| order_id | Order code sent by store at transaction creation. | < 40 AN |
| payment_type | Type of payment of the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = NR Bill via Web Service | = 1 A |
| sitef_usn | Unique sequential number of the pre-authorization transaction in SiTef. | = 6 N |
| status | Carat Portal Pre-Authorization Transaction Status. | = 3 AN |
| tid | Transaction ID in acquirer/routing. This field is only returned in transactions with acquirers external to SiTef. | < 40 AN |
| xid | XID field returned in 3DS authentications or certain acquirers/routes. | < 40 AN |
Attention: The code and message fields refer to the code and message referring to the query request. These do not refer to the queried transactions.
Request Example
Request Example
Shared Tables#
Carat Portal Transaction Status#
| Code | Name | Description |
|---|---|---|
| NEW | New | Newly created transaction. |
| INV | Invalid | Transaction was not created successfully, the store probably sent some incorrect parameter, and the transaction could not be initialized correctly. |
| PPC | Pending confirmation | Payment pending confirmation. |
| PPN | Undone | Pending payment not confirmed (cancelled). |
| PEN | Awaiting payment | Transaction awaiting response from the financial institution. |
| CON | Done | Transaction confirmed by the financial institution. |
| NEG | Denied | Transaction denied by the financial institution. |
| ERR | Error making payment | Error in communication with the authorizer. Try again. |
| BLQ | Blocked | Transaction blocked after multiple card lookup attempts. |
| EXP | Expired | The transaction expired due to the NIT expiration date. |
| EST | Reversed | Reversal payment. |