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",
    "payer": {
      "identification_number": "22222222222",
      "store_identification": "22222222222"
    },
    "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:

POSTMAN

RESTClient

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) If the merchant sends this field with value `true`, the `additional_data`.`payer`.`store_identification` field becomes mandatory.	< 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
`submerchant_split`	SUBMERCHANT_SPLIT object. 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. Exclusive functionality for payments (`transaction_type`:`payment`). The maximum number of items allowed in this array is 5 items. This should not be used together with the `method`:`split` field mentioned above, as it is a different functionality.		NO
`payer`	PAYER object		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

SUBMERCHANT_SPLIT[] (`submerchant_split`)#

[
   {
      "submerchant_code":"empresa01",
      "submerchant_amount":"120"
   },
   {
      "submerchant_code":"empresa02",
      "submerchant_amount":"420"
   },
   {
      "submerchant_code":"empresa03",
      "submerchant_amount":"300"
   },
   {
      "submerchant_code":"empresa04",
      "submerchant_amount":"400"
   },
   {
      "submerchant_code":"empresa05",
      "submerchant_amount":"250"
   }
]

Parameter	Description	Format	Mandatory
`submerchant_code`	BIN/Sipag merchant code	< 15 AN	NO
`submerchant_amount`	Transaction amount related to the merchant.	< 12 N	NO

PAYER (`payer`)#

{
    "store_identification": "card_1",
    "identification_number": "123123123"
}

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

Home

Transaction creation process#

Test tools#

Request parameters#

BACKURL (back_url)#

IATA (iata)#

ADDITIONALDATA (additional_data)#

SUBMERCHANT_SPLIT[] (submerchant_split)#

PAYER (payer)#