Payment with Idempotence

API interface that allows the online store to process sales requisitions.

Call Details

• Resource: /v2/payments
• HTTP Method: POST
• Request format: JSON
• Response format: JSON
• Header parameters:

Parameter	Description	Format	Mandatory
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
Content-Type	It must be sent with the value application/json.	= 15 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:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \

--header 'Content-Type: application/json' \

--header 'merchant_id: ************' \

--header 'merchant_key: ************' \

--header 'idempotency_key: ************' \

--data-raw '{

"merchant_usn": "12050620649",

"order_id": "121314",

"installments": "10",

"installment_type": "4",

"authorizer_id": "2",

"amount": "10000",

"card": {

"expiry_date": "1222",

"security_code": "123",

"number": "5555555555555555"

}

}'

--verbose

Response:

{

"code": "0",

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

"payment": {

"authorizer_code": "000",

"authorizer_message": "Transacao Aprov.",

"status": "CON",

"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",

"order_id": "121314",

"customer_receipt": "====CUPOM COMPRADOR====",

"merchant_receipt": "====CUPOM ESTABELECIMENTO====",

"authorizer_id": "2",

"acquirer_id": "229",

"acquirer_name": "Bin",

"authorizer_date": "14/07/2022T11:54",

"authorization_number": "145778",

"merchant_usn": "12050620649",

"esitef_usn": "220714103502410",

"sitef_usn": "145778",

"host_usn": "999145778 ",

"amount": "10000",

"payment_type": "C",

"issuer": "2",

"authorizer_merchant_id": "000000000000005",

"terminal_id": "ES000032",

"payment_date": "14/07/2022T11:54"

}

}

Payment using the same idempotency_key with different order_id

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \

--header 'Content-Type: application/json' \

--header 'merchant_id: **********' \

--header 'merchant_key: **********' \

--header 'idempotency_key: ************' \

--data-raw '{

"merchant_usn": "12050620649",

"order_id": "1657833175201",

"installments": "10",

"installment_type": "4",

"authorizer_id": "2",

"amount": "10000",

"card": {

"expiry_date": "1222",

"security_code": "123",

"number": "5555555555555555"

}

}'

Resposta:

{

"code": "1270",

"message": "Idempotent transaction body does not match the original",

"payment": {

"status": "INV",

"nit": "6ffad47ea1446d76160f1241f0fdca39342521df4f3f577920d9c855047fb9a2",

"order_id": "1657833175201",

"merchant_usn": "12050620649",

"esitef_usn": "230912025329730",

"amount": "10000"

}

}

Performing pre-authorization if the idempotency key is the same as that of a payment transaction

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/preauthorizations/' \

--header 'Content-Type: application/json' \

--header 'merchant_id: **********' \

--header 'merchant_key: **********' \

--header 'idempotency_key: ************' \

--data-raw '{

"merchant_usn": "12050620649",

"order_id": "1657833175201",

"installments": "10",

"installment_type": "4",

"authorizer_id": "2",

"amount": "11000",

"card": {

"expiry_date": "1222",

"security_code": "123",

"number": "5555555555555555"

}

}'

Response :

{

"code": "1272",

"message": "Idempotent transaction is not of the same type",

"payment": {

"status": "INV",

"nit": "d081e89daa1a0e446b92ead4ed2325f860d4e1280aa4b407f32957ce17f62ee3",

"order_id": "1657833175201",

"merchant_usn": "12050620649",

"esitef_usn": "230912025329774",

"amount": "2220"

}

}

Request parameters

The table below describes the request parameters of the transaction creation service:

WARNING: 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 sending Company and SiTef Terminal via REST. Passengers information Hotel reservation information Hotel address information Hotel rooms information Hotel room guests information Event information Event venue information Event tickets information Event attendee information Travel connections information Billing address information Travel information

Parameter	Description	Format	Mandatory
merchant_usn	Unique sequential number for each order, created by the merchant. The USN will be used during the whole communication with the merchant to help identifying the order. As it is a possible access key on the merchant's side, even though it's optional to Carat Portal, it's strongly recommended that the field is formatted and sent by the merchant's 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
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
authorizer_id	Code of the authorizer on Carat Portal. Learn more.	< 3 N	NO
amount	Total price of the purchase (in cents). Example: 1,00 = 100 or 1.100,00 = 110000 – send the value without the comma and the dots.	< 12 N	YES
soft_descriptor	Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more	< 30 AN	NO
card	Card data.
number	Customer's card number (PAN). Brand generated token (DPAN) for network token payment. Learn more	< 19 N	YES
expiry_date	Card expiry date in MMYY format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory.	= 4 N	COND.
security_code	Card security code. This field may not be mandatory if the company has an agreement in the contract established with the acquirers, only for payments of certain areas. However, it is possible to configure the mandatory field in the merchant settings, consult Carat support for more information. Important: a payment with schedule implies on storing the customer's card data on Carat Portal's environment. However, for security reasons, the security code cannot be stored. Therefore, the scheduled payments will always be executed without the security code.	< 5 N	COND.
holder	Card holder name. Only mandatory for payments with e-Rede, GetNet WS and VR (SmartNet).	< 30 AN	COND.
token	HASH of a card stored on Carat Portal. It's not allowed to send an ‘open' card number (number field) and a stored card (token field) on the same request.	= 88 AN	NO
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
external_authentication	This element receives MPI authentication result fields.
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.
financing_plan	Financing Plan code used for Via Certa Financiadora routed payments, only in case of installments plan with interest.	< 4 N	NO
special_code	Conductor/Renner SiTef routings general use code.	< 6 N	NO
mid	Acquirer merchant code - For BIN routings, the MID to be used by the merchant is unique. This field must be used if it is necessary to select a MID other than the default one.	< 15 AN	COND
recurrency	Flag that defines whether or not the payment is recurring. Accepted all routings via SiTef, Cielo e-Commerce, Global Payments WS, Stone WS, e.Rede REST and GetnetWS routings. In the case of a Stone WS recurrency, it is mandatory to send only one of the fields below, is_first_recurring OR is_subsequent_recurring.	< 5 T/F	NO
recurrency_tid	First transaction's TID. This field tells the first and the subsequent transactions apart. Use only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard and for GetnetWS routing.	< 16 AN	NO
is_first_recurring	Flag used only for StoneWS routing. Indicates that the transaction is the first in a series of recurring transactions.	< 5 T/F	COND.
is_subsequent_recurring	Flag used only for StoneWS routing. It indicates that the transaction is the second or nth of a series of recurring transactions, where n > 2.	< 5 T/F	COND.
recurrency_original_amount	Original value of the transaction that started the recurrency. This value must be informed in all subsequent recurrences. Used only for recurrence. Field used only in BIN routing, mandatory when recurrence	< 18 AN	NO
product_code	Product code. It is mandatory in routing via Marisa.	< 6 N	COND.
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
authorization_number	Authorization number. Mandatory for Bradescard Voucher authorizer.	< 6 AN	COND.
acquirer.vouchers_filter[]	Choice of vouchers that will not be accepted. Options of "Vouchers": 01 - Food, 02 - Meal, 03 - Culture, 04 - Fuel, 05 - Benefit. Example: You do not want to accept Vouchers: Culture, Fuel, Benefit. You must send: "vouchers_filter": ["03", "04", "05"]
acquirer.prefixes	Element for sending SiTef prefixes, like CICLOS, CPLANO and VLRADD. If the prefix that was sent is not supported by card, Carat Portal will invalidate the transaction, preventing that a false impression of the use of a functionality is given. Example: { "key" : "value" } -> { "CICLO" : "01" }
key	Prefix name.	< 1024 AN	NO
value	Prefix value.	< 1024 AN	NO
acquirer.submerchant_split[]	It consists of an array for split payments, unique to BIN and Sipag routing, both via SiTef. It allows the division of parts of the total amount of the payment among other merchants. The maximum number of items allowed in this array is 5 items.
submerchant_code	BIN/Sipag merchant code	< 51 AN	NO
submerchant_amount	Transaction amount related to the merchant	< 12 N	NO
acquirer.card_on_file	It is intended for sending specific information such as card storage authorization, confirming that the cardholder has authorized the storage of the card. Learn more.
usage	Identifies the usage. For instance, in case of storage authorization: authorized	< 11 AN	NO
reason	Itentifies the reason. For instance, in case of storage authorization: card	< 11 AN	NO
additional_data	Element for sending additional data.
postpone_confirmation	This field must be sent with value true if a payment with late confirmation is desired.	< 5 T/F	NO
visitor_id	Visitor identifier obtained using Konduto's JavaScript	< 40 AN	NO
description	Product description	< 100 AN	NO
discount_amount	Discount amount of the product in cents	< 10 N	NO
discount_info	Discount information.	< 500 AN	NO
sku	Item product code	< 100 AN	NO
creation_date	Indicates the date of publication of the product on the merchant's site (Format: DD/MM/YYYY)	= 10 AN	NO
additional_data.payer	Element for sending data related to the payer.
name	Customer name	< 100 AN	YES
surname	Customer surname	< 100 AN	YES
email	Customer e-mail	< 100 AN	YES
born_date	Customer birth date (format : YYYY-MM-DDTHH:MM:SS)	= 19 AN	NO
identification_number	Customer document number	< 100 AN	NO
creation_date	Account creation date on the site (format: DD/MM/YYYY )	= 10 AN	NO
is_new_client	Boolean that indicates if the customer is using a recently created account in this purchase	< 5 T/F	NO
is_vip_client	Boolean that indicates if the customer is VIP or a frequent buyer	< 5 T/F	NO
additional_data.merchant	Element for sending data related to the merchant.
email	Merchant's e-mail address.	< 1024 AN	NO
additional_data .passengers[]
name	Passenger first name	< 100 AN	YES
last_name	Passenger last name	< 100 AN	YES
legal_document	Passenger document	< 100 AN	YES
legal_document_type	Passenger document type (5 = passport, any other number = id)	< 8 AN	YES
birth_date	Passenger birth date (format: YYYY-MM-DDTHH:MM:SS)	< 17 AN	NO
nationality	Passenger nationality, following ISO 3166-1 alfa-3	= 3 AN	NO
is_frequent_traveler	Frequent traveler boolean	< 5 T/F	NO
is_with_special_needs	Boolean which indicates if it's a passenger with special needs	< 5 T/F	NO
frequent_flyer_card	Loyalty program type	< 255 AN	NO
customer_class	Loyalty program category	< 255 AN	NO
additional_data .hotel_reservations[]
hotel	Hotel name	< 100 AN	YES
category	Hotel category	< 100 AN	NO
additional_data .hotel_reservations[] .address
street_name	Hotel street name	< 255 AN	NO
street_number	Hotel street number	< 255 AN	NO
complement	Hotel address complement	< 100 AN	NO
city	Hotel city	< 100 AN	NO
state	Hotel state	< 100 AN	NO
zip_code	Hotel zip code	< 100 AN	NO
country	Hotel country code, following ISO 3166-1 alfa-3	= 3 AN	NO
additional_data .hotel_reservations[] .rooms[]
number	Room number	< 100 AN	NO
code	Room code	< 100 AN	NO
type	Room type	< 100 AN	NO
check_in_date	Check-in date and time (format: YYYY-MM-DDTHH:MM:SS)	< 17 AN	YES
check_out_date	Check-out date and time (format: YYYY-MM-DDTHH:MM:SS)	< 17 AN	NO
number_of_guests	Number of guests	< 9999 N	NO
board_basis	Feeding regime	< 100 AN	NO
additional_data .hotel_reservations[] .rooms[] .guests[]
name	Guest name	< 100 AN	YES
document	Guest document	< 8 AN	NO
document_type	Guest document type: cpf rg passport id other	< 8 AN	NO
birth_date	Guest birth date (format: YYYY-MM-DDTHH:MM:SS)	< 17 AN	NO
nationality	Guest nationality, following ISO 3166-1 alfa-3	= 3 AN
additional_data .events[]
name	Event name	< 255 AN	YES
date	Event date and time (format YYYY-MM-DDTHH:MM:SS)	< 17 AN	YES
type	Event type: show theater movies party festival course sports corporate	< 9 AN	YES
subtype	Event type details	< 255 AN	NO
additional_data .events[] .venue
name	Venue name	< 255 AN	NO
street_name	Venue street name	< 255 AN	NO
street_number	Venue street number	< 255 AN	NO
city	Venue city	< 255 AN	NO
state	Venue state	< 255 AN	NO
country	Venue country code, following ISO 3166-1 alfa-3	= 3 AN	NO
capacity	Venue capacity	< 255 AN	NO
additional_data .events[] .tickets[]
id	Unique ticket identifier	< 255 AN	NO
category	Ticket category: student senior government social regular	< 10 AN	YES
section	Ticket section	< 255 AN	NO
premium	Premium ticket indicator	< 5 T/F	NO
additional_data .events[] .tickets[] .attendee
name	Attendee name	< 255 AN	NO
document	Attendee document	< 100 AN	YES
document_type	Attendee document type: cpf cnpj rg passport other	< 100 AN	NO
birth_date	Attendee birth date (format: YYYY-MM-DDTHH:MM:SS)	< 17 AN	NO
additional_data.shipment.receiver_address
street_name	Shipment address street name.	< 255 AN	NO
street_number	Shipment address street number.	< 15 AN	NO
complement	Shipment address complement.	< 50 AN	NO
zip_code	Shipment zip code. E.G.: 21241-140.	< 9 AN	NO
city	Shipment city.	< 50 AN	NO
state	Shipment state.	= 2 AN	NO
country	Shipment country, following ISO 3166-1. E.G.: BRA	= 3 AN	NO
additional_data.browser
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
additional_data.items[]
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	Unit price of the product.	< 15 N	NO
additional_data.items[].passenger
email	Passenger email.	< 255 AN	NO
legal_document	Id of the passenger to whom the ticket was issued.	< 32 AN	NO
name	Passenger name.	< 120 AN	NO
customer_class	Classification of the Airline. Values such as Gold or Platinum can be used.	< 32 AN	NO
additional_data.items[].passenger.phone
ddi	Passenger phone IDD.	< 3 N	NO
ddd	Passenger phone DDD.	< 3 N	NO
number	Passenger phone number.	< 9 N	NO
additional_data.extra_param.acquirer_params[]
key	Id of the additional information to be sent. For further details about this field, see https://developercielo.github.io/Webservice-3.0/english.html#merchant-defined-data.	< 1024 N	NO
value	Value of additional information to be sent.	< 1024 AN	NO
additional_data.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
additional_data.shipment.phones[]
ddi	Addressee phone IDD.	< 3 N	NO
ddd	Addressee phone DDD.	< 3 N	NO
number	Addressee phone number.	< 9 N	NO
additional_data .connections[]
journey_type	OUTWARD - outward journey RETURN - return trip	< 7 AN	YES
origin_city	Origin city	< 100 AN	YES, if transport_type=bus
destination_city	Destination city	< 100 AN	YES, se transport_type=bus
from	IATA airport code of the origin airport	= 3 AN
to	IATA airport code of the destination airport	= 3 AN	YES, if transport_type=flight
departure_date	Departure date and time (format: YYYY-MM-DDTHH:MM:SS)	< 17 AN	YES
class	Seat class name (Ex: economy, business or first)	< 8 AN	NO
class_code	Seat class code	< 20 AN	NO
company	Airline name	< 20 AN	NO
additional_data .billing_data .address
street_name	Billing street name	< 255 AN	NO
street_number	Billing street number	< 255 AN	NO
complement	Billing address complement	< 100 AN	NO
city	Billing city	< 100 AN	NO
state	Billing state	< 100 AN	NO
zip_code	Billing zip code	< 100 AN	NO
country	Billing country code, following ISO 3166-1 alfa-3	= 3 AN	NO
additional_data .travel
transport_type	Travel transport type (flight or bus)	< 6 AN	YES
expiration_date	Expiration date (format: DD/MM/YYYY )	= 10 AN	NO

The table below describes the additional parameters that must be sent on a payment with fraud analysis (for the time being only available for Cielo e-Commerce):

Parameter	Description	Format	Mandatory
additional_data
anti_fraud_institution	Institution that will carry out the fraud analysis to the merchant. It must be send with the value AUTHORIZER.	= 10 AN	YES para análise de fraude
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 para análise de fraude
journey_type	Type of the trip. Allowed values: ROUND_TRIP – round trip. OUTWARD – outward. RETURN – return.	< 10 AN	NO

Response parameters

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the payment effectuation service:

Parameter	Description	Format
code	Carat Portal response code. Any code different from 0 means failure. Learn more.	< 4 N
message	Carat Portal response message.	< 500 AN
payment
authorizer_code	Authorizer response code.	< 10 AN
authorizer_message	Authorizer response message.	< 500 AN
status	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
nit	Identifier of the payment transaction on Carat.	= 64 AN
order_id	Order code sent by the merchant on the creation of the transaction.	< 40 AN
merchant_usn	Unique sequential number sent by the merchant on the creation of the transaction.	< 12 N
amount	Total price of the purchase specified by the merchant (in cents) on the creation of the transaction.	< 12 N
sitef_usn	Unique sequential number of the payment transaction on SiTef.	= 6 N
esitef_usn	Unique sequential number of the payment transaction on Carat Portal.	= 15 N
customer_receipt	Customer's receipt.	< 4000 AN
merchant_receipt	Merchant's receipt.	< 4000 AN
authorizer_id	Code of the authorizer used on the transaction.	< 4 N
acquirer_id	Code of the acquirer used on the transaction.	< 4 N
acquirer_name	Name of the acquirer used on the transaction.	< 100 AN
authorizer_date	Payment authorization date returned by the authorizer in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03	= 16 D
authorization_number	Authorization number.	< 6 AN
host_usn	Host USN.	< 15 AN
tid	ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef.	< 40 AN
eci	Eletronic Commerce Indicator (security level indicator of the payment transaction).	< 3 AN
payment_date	Payment authorization date on Carat Portal in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03	= 16 D
issuer	Issuer code returned by the authorizer.	< 5 AN
authorizer_merchant_id	Affiliation code of the merchant on the authorizer.	< 100 AN
xid	XID field returned on 3DS authentications or certain acquirers.	< 40 AN
cavv	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N
recurrency_tid	First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard.	< 16 AN
terminal_id	Terminal code used in the transaction	< 8 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
payment.analysis
status	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
code	Carat Portal response code. Any code different from 0 means failure. Learn more.	< 4 N
message	Carat Portal response message.	< 500 AN