Create transaction service

Transaction creation process

The transaction creation process must follow these steps:

• The transaction is created according to the parameters sent in the request key and represented by a JSON object via POST in the request;
• The merchant receives a success or error message, formatted as XML or JSON, according to the response_type parameter in the URL sent when starting a transaction.

URL to start a transaction via HTTPS POST:

Homologation environment:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/[response_type].se
Production environment:
https://esitef.softwareexpress.com.br/e-sitef/init/[response_type].se

Attention: The IP should never be used instead of the domain esitef-ec.softwareexpress.com.br (or esitef-homologacao.softwareexpress.com.br for the homologation environment). IP can change at any time and without notice, so it is important to always use the domain to access Carat Portal.

POST parameters:

• Key: request;
• Value: JSON object;
• [response_type]: json or xml;

JSON request example (JavaScriptObjectNotation):

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/json.se

Basic JSON request example:

{

"merchant_id": "codigoDaLoja",

"amount": "1800"

}

JSON object request with some additional parameters:

{

"merchant_id": "codigoDaLoja",

"order_id": "123456",

"redirect": "A",

"installments": "3",

"installment_type": "4",

"authorizer_id": "1",

"amount": "1800",

"transaction_type": "payment",

"back_url": {

"url_success": "",

"url_failure": "",

"url_cancel": ""

},

"additional_data": {

"currency": "BRL",

"method": "",

"postpone_confirmation": "false",

"max_installments_with_interest": "12",

"allowed_payment_methods": [{ "id": "CRD" }, { "id": "DBT" }]

}

}

Test tools

For initial testing in this interface, if necessary, some tools can be used in order to better understand REST communication:

• Application for Windows/Linux/Mac:
  • POSTMAN
• Firefox extension:
  • RESTClient

Sample screens of these tools:

Request parameters

The JSON additional_data object has fields that change according to the authorizer (authorizer_id) for the payment. For more details on the additional_data field, please refer to specific documentation for each authorizer supported by the HTML 2.0 Payment Interface.

{

"amount": "120000",

"authenticate": "false",

"authorizer_id": "1",

"installments": "1",

"installment_type": "4",

"merchant_id": "LOJATESTE",

"merchant_usn": "999888",

"order_id": "order123",

"recharge_included": "false",

"redirect": "M",

"soft_descriptor": "softDescriptor",

"store_card": "false",

"style": "N",

"transaction_type": "payment",

"payment_link":"false",

"additional_data": { },

"back_url": { },

"iata": { },

"recharge": { }

}

Parameter	Description	Format	Mandatory
amount	Total amount to be paid by the customer. Format: Must be sent in cents. e.g.: 1000 (10 dollars).	< 12 N	YES
authenticate	Parameter informing the need of transaction authentication. Allowed values: 0, 1, 2, 3 and 4. Default value – 0	< 1 A	NO
authorizer_id	Authorizer code (on Carat Portal)	< 10 A	NO
installments	Number of installments of the payment. The following authorizers do not allow prefixing this value, therefore in this case the parameter must not be sent: PayPal Mercado Pago PagSeguro For spot sale, this value must be 1.	< 2 N	NO
installment_type	Financing type chosen by the customer. Allowed values: 3 – installments with interest 4 – installments without interest Default value = 4.	= 1 N	NO
merchant_id	Merchant code on Carat Portal.	< 15 A	YES
merchant_usn	Identification code of the transaction generated by the merchant.	< 12 A	NO
order_id	Order code (generated by the merchant)	< 40 AN	NO
recharge_included	Informs if a recharge will be performed. Allowed values: true – if a recharge will be performed. false – if a recharge will not be performed. Default value – false	= 5 A	NO
redirect	Type of the redirection that will be performed after the end of the transaction flow on Carat Portal. Allowed values: A – (Automatic) automatic redirection: the final screen of the payment won't be shown (including the receipt) and the customer is automatically redirected to one of the url's of the parameter back_url. In addition, the nit parameter is sent along with a HTTP GET request. M – (Manual) manual redirection: Shows the final screen of the payment including the receipt and shows a link to the customer to click and be redirected to the merchant's web site. In addition, the nit parameter is sent with a HTTP POST request. Default value – M (Manual)	= 1 A	NO
soft_descriptor	Name of the establishment that will be presented in the credit card invoice. Learn more	< 30 A	NO
store_card	Indicates if the card used for the payment will be stored. Allowed values: true – Indicates that the card used for the payment will be stored. false – Indicates that the card used for the payment will not be stored. Default value – false (store will not be performed).	< 5 A	NO
style	Informs the redirection style to Carat Portal. Allowed values: N – Redirection at the same frame. P – A pop-up will be opened. Default value – N The merchant must inform the redirection style in order to Carat Portal handle properly the windows at the final of the payment transaction.	= 1 A	NO
transaction_type	Transaction type that will be performed. Allowed values: payment – In case of Payment preauthorization – In case of Pre-Authorization Default value – payment	< 32 A	NO
payment_link	This field must receive the value true to activate the payment link functionality.	< 5 A	NO
additional_data	ADDITIONALDATA object		NO
back_url	BACKURL object		NO
iata	IATA object		NO
recharge	RECHARGE object. Contains information related to a recharge transaction.		NO

BACKURL (back_url)

{

"url_cancel": "https://cancel.com",

"url_failure": "https://failure.com",

"url_success": "https://success.com"

}

Parameter	Description	Format	Mandatory
url_success	Redirection URL of the customer in case of success. Must have only the relative path.	< 200 A	NO
url_failure	Redirection URL of the customer in case of failure. Must have only the relative path.	< 200 A	NO
url_cancel	Redirection URL of the customer in case of cancel. Must have only the relative path.	< 200 A	NO

IATA (iata)

{

"departure_tax": "1000",

"first_installment": "20000"

}

Parameter	Description	Format	Mandatory
departure_tax	Departure tax amount.	< 200 A	NO
first_installment	First installment value.	< 200 A	NO

ADDITIONALDATA (additional_data)

{

"currency": "BRL",

"method": "",

"postpone_confirmation": "false",

"financing_plan": "",

"payer": { },

"allowed_payment_methods": [],

"max_installments_with_interest": ""

}

Parameter	Description	Format	Mandatory
currency	Default currency used for all the items in the purchase. Currency code according to the ISO 4217 standards. Some allowed values: BRL – Real VEF – Venezuelan bolívar fuerte USD – American Dollar GBP – Pound Among others. If this parameter is not sent, Carat Portal will use the merchant configuration, and if the merchant is not configured, the value BRL will be used as the default value.	= 3 A	NO
method	Used to perform differentiated transactions. Allowed values: split – Performs a SPLIT transaction.	< 1024 AN	NO
postpone_confirmation	Allows the merchant to keep the transaction as Pending Confirmation, and later, confirm or cancel it.	< 5 A	NO
financing_plan	Financing Plan code. Required only in payments in installments and with interests routed by Via Certa. It must be sent only if authorizer_id (Via Certa routed authorizer), installments (>1) and installments_type (3 = with interest) fields were also sent in this step.	< 4 AN	NO
max_installments	Maximum installments without interest that will be presented to the payer at the checkout. If informed, it will overwrite the value configured in the Carat Portal store. If the acquirer also returns a maximum value of installments, the value used will always be the smallest.	< 3 N	NO
max_installments_with_interest	Maximum installments with interest that will be presented to the buyer at checkout. If informed, it will overwrite the value configured in the Carat Portal store. If the acquirer also returns a maximum amount of installments, the amount to be used will always be the smallest.	< 2 N	NO
allowed_payment_methods	ALLOWED_PAYMENT_METHODS object It consists of an array containing all payment methods that will be displayed in the payment flow authorizer selection screen. Learn more.		NO
mcc	The MCC (Merchant Category Code) is a code that classifies the business by the type of goods or services it provides. This field is used by the sub-merchant funding functionality via SiTef.	4 N	NO
subacquirer_merchant_id	It is the merchant identification for the subacquirer. This field is used by the sub-merchant funding functionality via SiTef.	22 N	NO
multiple_payment_methods	Indicates if the merchant will allow the customer to pay using two payment methods. Do not send this field as true when prefixing an authorizer.	< 5 T/F	NO

Parameter	Description	Format	Mandatory
store_identification	Identification of the owner of the card to be stored. This identification must be unique for each of the merchant's customers. Attention: assuring uniqueness is a responsibility of the merchant. Carat Portal does not perform any validation.	< 20	NO
identification_number	Payer's identification number.	< 1024	NO

ALLOWED_PAYMENT_METHODS[] (allowed_payment_methods)

[

{

"id":"CRD"

},

{

"id":"DBT"

},

{

"id":"WLT"

}

]

Parameter	Description	Format	Mandatory
id	Identifier of the payment method to be exhibited on buyer screen during payment flow. The following values are accepted: CRD - Credit, DBT - Debit, BLT - Boleto, PIX - Pix, WLT - Wallet, GFT - Prepaid or voucher. If no value is sent, all fields allowed by the store configuration are displayed.	< 3 AN	NO

Note 1: The parameters specification of the additional_data object may vary according to the authorizer. See the specific documentation for more details.

Note 2: In the case of pre-fixed installments that declare the installments and installment_type fields without the authorizer_id definition, the following rules will apply to the available authorizers options that Carat Portal will present to the customer:

• The wallets (Visa Checkout, Masterpass, GooglePay), PayPal, PagSeguro and MercadoPago options will be omitted. The reason is that installments options can be defined by the consumer inside the payment method's environment.
• If the payment has more than one installment (installments > 1), only credit options will be shown and, from these options, only those that match the installments configuration in merchant's registration in Carat Portal.

Advice: Adjust these Carat Portal configurations as agreed with acquirers. For more details, please contact Carat Portal support team, or access the Merchant's Portal.

Attention: In case of iCards via Sitef routed payments, the fields authorizer_id, installments, and installment_type must be pre-fixed in transaction creation step. So it is not possible to the user choose or change this information during the browsing.

Response parameters

The response of the transaction creation operation (JSON format):

{

"responseCode": 0,

"description": "OK. Transaction successful.",

"url": "https://{{url}}/e-sitef/do.se?input['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",

"nsuesitef": "123456789012345",

"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"

}

The returned fields are described in table below:

Parameter	Description	Format
responseCode	Carat Portal response code. Any code different from 0(zero) means failure. Learn more.	< 5 N
description	Response description.	< 1024 A
url	Redirection URL to begin the payment.	< 256 A
nit	Transaction identifier on Carat Portal.	= 64 A
nsuesitef	USN (Unique Sequential Number) of the transaction on Carat Portal.	= 15 A