Cielo

The merchant can configure its credit card transactions on Carat Portal to be routed to many acquirers, such as Cielo e-Commerce.

In this document, we will be using the nomenclature “CieloEC” to reference this acquirer.

Therefore, the merchant can configure Carat Portal to route VISA transactions to CieloEC and MASTERCARD transactions to e-Rede, for example.

Supported Carat Portal interfaces

The following interfaces are supported for integration with CieloEC:

• REST PreAuthorization
• REST Payment
• REST Cancel
• HTML Payment
• HTML Pre Authorization

Attention: This integration also allows 3DS authentication data (eci, reference_id and cavv) to be sent. Learn more about this service.

Supported authorizers

Listed below are the authorizers supported to be routed to CieloEC coupled with their respective IDs:

• CREDIT

  • VISA (1)
  • MASTERCARD (2)
  • AMERICAN EXPRESS (3)
  • ELO (41)
  • AURA (6)
  • JCB (43)
  • DINERS (33)
  • DISCOVER (44)

• DEBIT

  • VISA ELECTRON (221)
  • MASTERCARD DÉBITO (286)

• ELETRONIC TRANSFER

  • BRADESCO (8)
  • BANCO DO BRASIL (408)

• ZERO DÓLLAR

  • VISA (1)
  • VISA ELECTRON (221)
  • MASTERCARD (2)
  • MASTERCARD DÉBITO (286)
  • ELO (41)

Required credentials

The merchant must obtain from CieloEC the credentials listed below and send them to Software Express or register them as explained in the next item of this document.

Field	Description	Format
merchantID	Merchant's identification on CieloEC.	< 36 AN
merchantKey	Public key for double authentication on CieloEC.	< 40 AN

Important: HTML Payment: if these credentials are not registered, the corresponding authorizer won't be shown at the authorizer selection screen.

Registering information on the merchant's portal

The merchant itself can register the information obtained from CieloEC on Carat Portal's merchant's portal. It is also possible to change configurations. For this purpose, the merchant must select the desired authorizer and enter the editing screen as in the example below:

Registering SoftDescriptor on Carat Portal

Registering softDescriptor is optional, has 13 characters of max size, does not accept special characters and is only available for Visa and Mastercard.

Flows

In this section, the CieloEC transactional flow particularities will be presented.

REST Payment

This interface supports the sending of external authentication fields

Credit

You can send the fields below during the payment effectuation step:

Parameter	Description	Format	Mandatory
card
holder	Holder name printed on the card	< 25 AN	NO
external_authentication
eci	Eletronic Commerce Indicator – Card holder authentication security level indicator.	< 3 N	NO
xid	Authentication cardholder's transaction identifier in 3DS, performed in a service external to Carat (In our 3DS, the xid is referenced by three_ds_server.trans_id in the return of the 3DS transaction creation service).	< 40 N	Conditional (required only for 3DS 2.0 authenticated transactions)
cavv	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO
version	3DS version used in authentication process.	1 AN	YES, when the 3DS version is 2
reference_id	RequestID returned in authentication process.	36 AN	YES, when the 3DS version is 2

Credit with authentication

You can send the field below during the transaction creation step:

Parameter	Description	Format	Mandatory
authorizer_authentication	Identifies whether the merchant wants a payment with authentication. If positive, send true.	< 5 AN	YES for credit with authentication

If the payment is successful, our service will return the transaction with status PEN (pending) and the following field will be present:

Parameter	Description	Format
authentication_url	URL for which the merchant must redirect its customer for its authentication.	< 56 AN

After a successful authentication, the payment will always be confirmed (CON status), which means that it isn't possible to do a credit with authentication without auto confirmation.

On the image below you can check how a transaction with authentication works:

Debit

With the exception of Corona Voucher transactions, all debit operations always require authentication and, hence, the authorizer_authentication field is not considered. The debit flow is the same of a credit with authentication.

Every debit transaction is auto-confirmed, so it is not allowed an debit with postpone confirmation.

Credit with fraud analysis

To do a credit with fraud analysis, it's necessary to send the additional_data field with additional information. Its value follows the JSON format as in the example below:

{

"amount":"1000",

"authorizer_id":"1",

"installments":"1",

"installment_type":"4",

"additional_data":{

"payer":{

"name":"Comprador",

"surname":"credito AF",

"email":"compradorteste@live.com",

"city":"Rio de Janeiro",

"state":"RJ",

"address_street_name":"Rua Jupiter",

"address_street_number":"174",

"address_zip_code":"21241140",

"born_date":"1991-01-02T08:30:00",

"address_street_complement":"AP 201",

"address_country":"BRA"

},

"shipment":{

"method":"LOW_COST",

"name":"Sr Comprador Teste",

"phones":[

{

"number":"21114740",

"ddd":"16",

"ddi":"55"

}

],

"receiver_address":{

"complement":"AP 201",

"city":"Rio de Janeiro",

"state":"RJ",

"country":"BRA",

"zip_code":"21241140",

"street_number":"174",

"street_name":"Rua Jupiter"

}

},

"connections":[

{

"from":"RAO",

"to":"SAO",

"flight_date":"2020-01-02T20:15:00"

}

],

"gift":"false",

"browser":{

"email":"compradorteste@live.com",

"agent":"Chrome",

"cookies_accepted":"false",

"host_name":"Teste",

"ip_address":"200.190.150.350"

},

"items":[

{

"title":"ItemTeste",

"quantity":"1",

"id":"1487337308522",

"risk":"HIGH",

"hedge":{

"time":"NORMAL",

"host":"OFF",

"nonSensical":"OFF",

"obscenities":"OFF",

"phone":"OFF",

"velocity":"HIGH"

},

"passenger":{

"name":"Comprador accept",

"email":"compradorteste@live.com",

"rating":"ADULT",

"phone":{

"number":"999994444",

"ddd":"11",

"ddi":"55"

},

"legal_document":"1234567890",

"customer_class":"Gold"

},

"unit_price":"1000",

"category_id":"other",

"gift_category":"OFF"

}

],

"extra_param":{

"acquirer_params":[

{

"key":"95",

"value":"Eu defini isso"

}

]

},

"anti_fraud":"enabled_before_auth",

"anti_fraud_institution":"AUTHORIZER",

"anti_fraud_criteria":"ALWAYS",

"finger_print_id":"074c1ee676ed4998ab66491013c565e2",

"returns_accepted":"true",

"journey_type":"OUTWARD"

}

}

The following table describes the fields in the JSON:

Additional customer data Additional shipment address data Browser additional data Product additional data Product purchase additional data Passenger additional data Passenger phone number additional data Acquirer additional parameters Shipment service additional data Addressee phone number data Flight connections data

Parameter	Description	Format	Mandatory
anti_fraud_institution	Institution that will carry out the fraud analysis to the merchant. It must be sent with the value AUTHORIZER.	< 10 AN	YES for fraud analysis
anti_fraud	Enables the fraud analysis service. Allowed values: enabled_before_auth – fraud analysis will be done BEFORE the payment authorization. If the analysis is rejected, the payment won't be initiated. enabled_after_auth – fraud analysis will be done AFTER the payment authorization. If the analysis is rejected, the payment will be cancelled.	< 19 AN	YES for fraud analysis
anti_fraud_criteria	Criteria for fraud analysis execution. Allowed values: ON_SUCCESS – only perform the analysis if the transaction had succeeded. ALWAYS – always perform the analysis.	< 10 AN	NO
finger_print_id	Identifier used to cross-check information obtained by the internet user's Browser with the data sent for analysis. This same value must be passed in the SESSIONID variable of the DeviceFingerPrint script. Learn more	< 50 AN	NO
gift	Boolean that indicates whether the order is a gift or not.	< 5 T/F	NO
returns_accepted	Boolean that defines whether returns are accepted for this order.	< 5 T/F	NO
journey_type	Type of the trip. Allowed values: ROUND_TRIP OUTWARD RETURN	< 10 AN	NO
payer
name	Customer name.
Note: the concatenation of name and surname must not surpass 255 characters.	< 200 AN	NO
surname	Customer surname.
Note: the concatenation of name and surname must not surpass 255 characters.	< 200 AN	NO
email	Customer email	< 255 AN	NO
born_date	Customer birthdate, in the YYYY-MM-DDTHH:MM:SS format e.g. 1991-01-02T08:30:00	19 AN	NO
adress_street_name	Customer street name address	< 255 AN	NO
adress_street_number	Customer street number address	< 15 AN	NO
adress_street_complement	Customer street complement address	< 50 AN	NO
adress_zip_code	Customer zip code address e.g. 21241140.	< 9 AN	NO
city	Customer city address	< 9 AN	NO
state	Customer state address e.g. SP	2 AN	NO
address_country	Customer country address e.g. BRA	< 35 AN	NO
shipment .receiver_address
street_name	Street name shipment address	< 255 AN	NO
street_number	Street number shipment address	< 15 AN	NO
complement	Complement shipment address	< 50 AN	NO
zip_code	Zip code shipment address Ex.: 21241-140.	< 9 AN	NO
city	City shipment address	< 50 AN	NO
state	State shipment address	< 2 AN	NO
country	Shipment country, following ISO 3166-1, e.g. BRA	3 AN	NO
browser
cookies_accepted	Boolean to identify whether the customer's browser accepts cookies. Send true if positive.	< 5 AN	NO
email	Email registered in the customer's browser.	< 100 AN	NO
host_name	Host name where the customer was before entering the store's website.	< 60 AN	NO
ip_address	Customer's IP address. It is strongly recommended sending this field.	< 15 AN	NO
agent	Name of the browser used by the customer, e.g. Chrome.	< 40 AN	NO
items[]
gift_category	Field that will evaluate the billing and delivery addresses for different cities, states or countries. Allowed values: OFF - Ignores fraud analysis for divergent addresses. YES - In case of divergence between billing and delivery addresses, mark with small risk. NO - In case of divergence between billing and delivery addresses, mark with high risk.	< 3 AN	NO
risk	Product risk level. Allowed values: LOW - The product has a history of few chargebacks. NORMAL - The product has a history of chargebacks considered normal. HIGH - The product has a history of chargebacks above average.	< 6 AN	NO
title	Product name.	< 255 AN	NO
quantity	Quantity of the product to be acquired.	< 15 N	NO
id	Product identifier.	< 255 AN	NO
unit_price	Product unit price in cents.	< 15 N	NO
category_id	Product type. Allowed values: art, baby, coupon, donation, computing, camera, video_game, television, car_electronic, electronic, automotive, entertainment, fashion, game, home, musical, phone, service, learning, ticket, travel, virtual_good, physical, other, adult_content, gift_certificate, handling, shipping, shipping_and_handling or subscription	< 21 AN	NO
items[] .hedge
time	Level of importance of client order day time. Allowed values: LOW - Low importance in the time of day when the purchase was made, for the fraud analysis. NORMAL - Normal importance in the time of day when the purchase was made, for the fraud analysis. HIGH - High importance in the time of day when the purchase was made, for the fraud analysis. OFF - Purchase time does not affect fraud analysis.	< 6 AN	NO
host	Level of importance of email and IP addresses of clients at scoring risk. Allowed values: LOW - Low importance of e-mail and IP address in fraud analysis. NORMAL - Normal importance of e-mail and IP address in fraud analysis. HIGH - High importance of e-mail and IP address in fraud analysis. OFF - E-mail and IP address do not affect fraud analysis.	< 6 AN	NO
non_sensical	Level of testing performed on buyer data with meaningless received orders. Allowed values: LOW - Low importance of the verification made on the buyer's order, in fraud analysis. NORMAL - Normal importance of the verification made on the buyer's order, in fraud analysis. HIGH - High importance of the verification made on the buyer's order, in fraud analysis. OFF - Verification of buyer's order does not affect fraud analysis.	< 6 AN	NO
obscenities	Level of obscenity of received orders. Allowed values: LOW - Low importance of obscenity verification of buyer's order, in fraud analysis. NORMAL - Normal importance of obscenity verification of buyer's order, in fraud analysis. HIGH- High importance of obscenity verification of buyer's order, in fraud analysis. OFF - Obscenity verification of buyer's order does not affect fraud analysis.	< 6 AN	NO
phone	Level of tests performed with the telephone numbers. Allowed values: LOW - Low importance on tests performed with the telephone numbers. NORMAL - Normal importance on tests performed with the telephone numbers. HIGH - High importance on tests performed with the telephone numbers. OFF - Phone number tests do not affect fraud analysis.	< 6 AN	NO
velocity	Level of importance of customer purchase frequency. Allowed values: LOW - Low importance in the number of purchases made by the customer in the last 15 minutes. NORMAL - Normal importance in the number of purchases made by the customer in the last 15 minutes. HIGH - High importance in the number of purchases made by the customer in the last 15 minutes. OFF - The frequency of purchases made by the customer does not affect the fraud analysis.	< 6 AN	NO
items[] .passenger
email	Passenger email.	< 255 AN	NO
legal_document	Passenger ID	< 32 AN	NO
name	Passenger name	< 120 AN	NO
rating	Passenger classification. Allowed values: ADULT - Adult passenger. CHILD - Child passenger. INFANT - Infant passenger. YOUTH - Teenage passenger. STUDENT - Student passenger. SENIOR_CITIZEN - Elderly passenger. MILITARY - Military passenger.	< 14 AN	NO
customer_class	Airline classification. Values such as Gold or Platinum can be used.	< 32 AN	NO
items[] .passenger .phone
ddi	Passenger phone IDD.	< 3 N	NO
ddd	Passenger phone DDD.	< 3 N	NO
number	Passenger phone number.	< 9 N	NO
extra_param .acquirer_params[]
key	Id of the additional information to be sent. Learn more	< 1024 N	NO
value	Value of additional information to be sent.	< 1024 AN	NO
shipment
name	Delivery recipient name.	< 255 AN	NO
method	Type of product delivery service. Allowed values: SAME_DAY – Delivery on the same day. ONE_DAY – Delivery overnight or on the next day. TWO_DAY – Delivery in two days. THREE_DAY – Delivery in three days. LOW_COST – Low cost delivery service. PICKUP – Product to be picked up in the store. OTHER – Other method. NONE – No delivery service, as it is a service or subscription.	< 9 AN	NO
shipment .phones
ddi	Addressee phone IDD.	< 3 AN	NO
ddd	Addressee phone DDD.	< 3 AN	NO
number	Addressee phone number.	< 9 AN	NO
connections[]
flight_date	Date, hour and minute of flight departure in the YYYY-MM-DDTHH:MM:SS format, e.g. 1991-01-02T08:30:00.	< 19 AN	NO
from	Airport code of the starting point of the trip, e.g. CGH.	< 3 AN	NO
to	Airport code of the ending point of the trip, e.g. GYN.	< 3 AN	NO

Additionally, this operation will return the following fields:

Fraud analysis data

Parameter	Description	Format
payment .analysis
code	Fraud analysis response code.	< 4 N
message	Fraud analysis response message.	< 200 AN
status	Fraud analysis transaction status on Carat Portal. This field can take the following values: NOV – New. EXP – Expired. ACC – Accepted REJ – Rejected REV – Reviewing INV – Invalid	3 AN

Zero Dollar

The Zero Dollar call consists of a payment call with the amount field with a value equal to zero and can be made to Visa, Mastercard and Elo, Credit and Debit, using the REST interface.

HTML Payment

The topics below refer to the transaction creation phase, in which the merchant sends a JSON document to Carat Portal. For further information on how to make a payment using the HTML interface, check HTML Payment page.

Credit

No particularities in comparison to other acquirers.

Credit with authentication

To perform a credit with authentication, the parameter below must be sent:

Parameter	Description	Format	Mandatory
authorizer_authentication	Identifies whether the merchant wants a payment with authentication. If positive, send true.	< 5 AN	YES for credit with authentication

Example:

{

"merchant_id": "LOJATESTE",

"order_id": "20150925001",

"amount": "1000",

"transaction_type": "payment",

"authorizer_authentication": "true"

}

As transactions with authentication are always confirmed, it isn't possible to postpone the confirmation (postpone_confirmation parameter).

Debit

Debit operations always require authentication and, hence, the authorizer_authentication field is not considered.

Every debit transaction is auto-confirmed, so it is not allowed an debit with postpone confirmation.

Credit with fraud analysis

The merchant must send in the additional_data element the fraud analysis fields. Example:

{

"merchant_id": "LOJACIELOEC",

"merchant_usn": "9876",

"order_id": "11",

"redirect": "M",

"authorizer_id": "",

"amount": "1000",

"installments": "",

"installment_type": "",

"style": "N",

"soft_descriptor": "",

"transaction_type": "payment",

"back_url": {

"url_success": "lojateste/loja/loja-index.jsp?pagina=sucesso",

"url_failure": "lojateste/loja/loja-index.jsp?pagina=fracasso",

"url_cancel": "lojateste/loja/loja-index.jsp?pagina=fracasso"

},

"additional_data": {

"payer": {

"name": "Comprador",

"surname": "credito AF",

"email": "compradorteste@live.com",

"city": "Rio de Janeiro",

"state": "RJ",

"address_street_name": "Rua Jupiter",

"address_street_number": "174",

"address_zip_code": "21241140",

"born_date": "1991-01-02T08:30:00",

"address_street_complement": "AP 201",

"address_country": "BRA"

},

"shipment": {

"method": "LOW_COST",

"name": "Sr Comprador Teste",

"phones": [

{

"number": "21114740",

"ddd": "16",

"ddi": "55"

}

],

"receiver_address": {

"complement": "AP 201",

"city": "Rio de Janeiro",

"state": "RJ",

"country": "BRA",

"zip_code": "21241140",

"street_number": "174",

"street_name": "Rua Jupiter"

}

},

"connections": [

{

"from": "RAO",

"to": "SAO",

"flight_date": "2020-01-02T20:15:00"

}

],

"gift": "false",

"browser": {

"email": "compradorteste@live.com",

"agent": "Chrome",

"cookies_accepted": "false",

"host_name": "Teste",

"ip_address": "200.190.150.350"

},

"items": [

{

"title": "ItemTeste",

"quantity": "1",

"id": "1488392648367",

"risk": "HIGH",

"hedge": {

"time": "NORMAL",

"host": "OFF",

"17efine17ical": "OFF",

"obscenities": "OFF",

"phone": "OFF",

"velocity": "HIGH"

},

"passenger": {

"name": "Comprador accept",

"email": "compradorteste@live.com",

"rating": "ADULT",

"phone": {

"number": "999994444",

"ddd": "11",

"ddi": "55"

},

"legal_document": "1234567890",

"customer_class": "Gold"

},

"unit_price": "1000",

"category_id": "other",

"gift_category": "OFF"

}

],

"extra_param": {

"acquirer_params": [

{

"key": "95",

"value": "Eu 17efine isso"

}

]

},

"anti_fraud": "enabled_before_auth",

"anti_fraud_institution": "AUTHORIZER",

"anti_fraud_criteria": "ALWAYS",

"finger_print_id": "074c1ee676ed4998ab66491013c565e2",

"returns_accepted": "true",

"journey_type": "OUTWARD"

}

}

Electronic Transfer

No particularities in comparison to other acquirers.

REST Pre Authorization

Credit

You can send the fields below during the pre-authorization effectuation step:

Parameter	Description	Format	Mandatory
card
holder	Holder name printed on the card	< 25 AN	NO
external_authentication
eci	Eletronic Commerce Indicator – Card holder authentication security level indicator.	< 3 N	NO
xid	Authentication cardholder's transaction identifier in 3DS, performed in a service external to Carat (In our 3DS, the xid is referenced by three_ds_server.transId in the return of the 3DS transaction creation service).	< 40 N	Conditional (required only for 3DS 2.0 authenticated transactions)
cavv	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO
version	3DS version used in authentication process.	1 AN	YES, when the 3DS version is 2
reference_id	RequestID returned in authentication process.	36 AN	YES, when the 3DS version is 2

Credit with fraud analysis

To perform a credit with fraud analysis, it's necessary to send the additional_data with additional information. Its format is the same described here.

Additionally, the following fields will be returned:

Fraud analysis data

Parameter	Description	Format
pre_authorization .analysis
code	Fraud analysis response code.	< 4 N
message	Fraud analysis response message.	< 200 AN
status	Fraud analysis transaction status on Carat Portal. This field can take the following values: NOV – New. EXP – Expired. ACC – Accepted REJ – Rejected REV – Reviewing INV – Invalid	3 AN

Installments

Installment data must be sent on the pre authorization phase and, if they are not sent, Carat Portal assumes spot sale. Then, on the capture step, the same installment data must be sent.

HTML Pre Authorization

The topics below refer to the transaction creation phase, in which the merchant sends a JSON document to Carat Portal. For further information on how to make a pre authorization using the HTML interface, check Pre Authorization Page.

Credit with/without fraud analysis

The parameters must be sent in the same format of a HTML payment.

Installments

On the capture phase, the same data used on the pre authorization must be sent.

REST Cancel

Learn more about this interface.

Test cards

Cielo has the following card for testing:

Issuer	Card number	Expiry date	CVV
VISA	4024007197692931	12/2022	123

Restrictions

CieloEC doesn't support IATA payments (International Air Transport Association).

Dynamic MCC Fields

Payment and Pre-Authorization REST Transaction creation service

Request Parameters

Additionally to the fields in the REST Transaction Creation Service, the fields below are used specifically in dynamic MCC transactions integrated to the Cielo EC routing:

Element for sending additional data. Element for sending data related to a subacquirer's merchant.

Parameter	Description	Format	Mandatory
soft_descriptor	Personalized phrase that will be printed on the bearer's invoice. For information regarding the dynamic MCC, it is equivalent to the name of the submerchant.	< 18 AN	YES
additional_data
mcc	Submerchant's MCC.	= 4 N	YES
subacquirer_merchant_id	Submerchant's code. Deprecated field!!! Use additional_data.subacquirer_merchant.id instead.	< 15 N	NO
additional_data.subacquirer_merchant
id	Submerchant's code.	< 15 N	YES
phone_number	Submerchant's phone number.	< 14 AN	NO
address	Submerchant's address.	< 48 AN	NO
city	Submerchant's city.	< 13 AN	NO
state	Submerchant's state, in two-digit acronym format (e.g.: SP).	= 2 A	YES
country	Submerchant's country. Follow the standard ISO 3166-1 alpha-2 (e.g.: BR).	= 2 A	YES
zip_code	Submerchant's zip code.	< 9 AN	YES
identification_number	Submerchant's CNPJ.	< 18 N	YES
payment_facilitator_id	Facilitator's code.	< 11 N	YES

Example

Request:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"merchant_usn": "19035815234",

"order_id": "1616438400044",

"installments": "1",

"installment_type": "4",

"authorizer_id": "2",

"amount": "1300",

"soft_descriptor": "L012121",

"additional_data": {

"mcc": "1111",

"subacquirer_merchant": {

"id": "12345",

"address": "Avenida Paulista, 2000",

"city": "São Paulo",

"state": "SP",

"country": "BR",

"zip_code": "01107001",

"identification_number": "53455823000178",

"payment_facilitator_id": "654321",

"phone_number": "+55 11 99999-9999"

}

}

}

Response:

{

"code": "0",

"message": "OK. Transaction successful.",

"payment": {

"status": "NOV",

"nit": "6215a32a557f5dc4627b540f517e40abd6a8411cf89a2e073913aa25d7c95590",

"order_id": "1616438400044",

"merchant_usn": "19035815234",

"amount": "1300"

}

}

Payment and Pre-Authorization REST effectuation service

In addition to the fields mentioned in REST Payment effectuation service and REST Pre-Authorization effectuation service, the fields below are used specifically in dynamic MCC transactions integrated to the Cielo EC routing:

Parameter	Description	Format	Mandatory
soft_descriptor	Personalized phrase that will be printed on the bearer's invoice. For information regarding the dynamic MCC, it is equivalent to the name of the submerchant. Required only if it was not sent in the soft_descriptor of the transaction initialization step.	< 18 AN	YES
mcc	Submerchant's MCC. Required only if it was not sent in the additional_data.mcc of the transaction initialization step.	= 4 N	YES
subacquirer_merchant_id	Submerchant's code. Required only if it was not sent in the additional_data.subacquirer_merchant.id of the transaction initialization step.	< 15 N	NO

ATTENTION!

It is in the transaction effectuation step that we send the accumulated dynamic MCC data. However, if the mcc field is not sent at any time and is not registered, the other dynamic MCC fields will not be passed on. This field is necessary to identify that the merchant wants to send sub-acquisition data.

Example

Request:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card": {

"number": "4024007197692931",

"expiry_date": "1222",

"security_code": "123"

}

}

Response:

{

"code": "0",

"message": "OK. Transaction successful.",

"payment": {

"authorizer_code": "6",

"authorizer_message": "Operation Successful",

"status": "CON",

"nit": "6215a32a557f5dc4627b540f517e40abd6a8411cf89a2e073913aa25d7c95590",

"order_id": "1616438400044",

"customer_receipt":"=== CUSTOMER RECEIPT ===",

"merchant_receipt":"=== MERCHANT RECEIPT ===",

"authorizer_id": "2",

"acquirer_id": "201",

"acquirer_name": "Cielo e-Commerce",

"authorizer_date": "22/03/2021T15:40",

"authorization_number": "316176",

"merchant_usn": "19035815234",

"esitef_usn": "210322068747730",

"host_usn": "362400",

"tid": "9fcd1663-0662-4761-9b9b-b269217cfc32",

"amount": "1300",

"payment_type": "C",

"authorizer_merchant_id": "6d29e58f-b29f-4e7e-8bf2-4d53b71acc1e",

"payment_date": "22/03/2021T15:40"

}

}

Fields conversion table

The conversion table between Cielo ECommerce fields and Carat Portal fields is presented below.

Cielo EC field	Carat Portal field	Observations
Softdescriptor(1)	soft_descriptor	The Carat Portal field soft_descriptor can be sent in the transaction creation request or be registered by the Carat Portal Support Team.
EstablishmentCode(3)	additional_data / subacquirer_merchant / payment_facilitator_id or paymentFacilitatorId	The Carat Portal PaymentFacilitatorID field can be sent in the transaction creation request or configured when the user defines a routing using Cielo ECommerce. In the latter case, this field can be edited in the Merchant Portal ("Autorizadoras" > "Configurar Autorizadoras") or by sending a request to the Carat Portal Support Team.
Mcc(2)	additional_data / mcc or mcc	The Carat Portal field mcc can be sent in the transaction creation request or be registered by the Carat Portal Support Team.
EstablishmentCode(2)	additional_data / subacquirer_merchant_id or additional_data / subacquirer_merchant / id or subacquirer_merchant_id or subacquirerMerchantId	The SubMerchant / SubMerchantID field can be sent in the transaction creation request, REST payment or pre-authorization effectuation request or configured when the user defines a routing using Cielo ECommerce. In the latter case, this field can be edited in the Merchant Portal ("Autorizadoras" > "Configurar Autorizadoras") or by sending a request to the Carat Portal Support Team.
Identity(2)	additional_data / subacquirer_merchant / identification_number	This field can be sent in the transaction creation. Contact the Carat Portal Support Team to register or change the default value of this field in your store.
Address(2)	additional_data / subacquirer_merchant / address	This field can be sent in the transaction creation. Contact the Carat Portal Support Team to register or change the default value of this field in your store.
City(2)	additional_data / subacquirer_merchant / city	This field can be sent in the transaction creation. Contact the Carat Portal Support Team to register or change the default value of this field in your store.
State(2)	additional_data / subacquirer_merchant / state	This field can be sent in the transaction creation. Contact the Carat Portal Support Team to register or change the default value of this field in your store.
CountryCode(2)	additional_data / subacquirer_merchant / country	This field can be sent in the transaction creation. Contact the Carat Portal Support Team to register or change the default value of this field in your store.
PostalCode(2)	additional_data / subacquirer_merchant / zip_code	This field can be sent in the transaction creation. Contact the Carat Portal Support Team to register or change the default value of this field in your store.
PhoneNumber(2)	additional_data / subacquirer_merchant / phone_number	This field can be sent in the transaction creation. Contact the Carat Portal Support Team to register or change the default value of this field in your store.

Structures
(1) Payment
(2) PaymentFacilitator.SubEstablishment
(3) PaymentFacilitator