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:[response_type].se
Production environment:[response_type].se

Attention: The IP should never be used instead of the domain (or 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):


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:

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",
"additional_data": { },
"back_url": { },
"iata": { },
"recharge": { }
amountTotal amount to be paid by the customer.
Must be sent in cents.
e.g.: 1000 (10 dollars).
< 12 NYES
authenticateParameter informing the need of transaction authentication.
Allowed values:
0, 1, 2, 3 and 4.
Default value – 0
< 1 ANO
authorizer_idAuthorizer code (on Carat Portal)< 10 ANO
installmentsNumber 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 NNO
installment_typeFinancing type chosen by the customer.
Allowed values:
3 – installments with interest
4 – installments without interest
Default value = 4.
= 1 NNO
merchant_idMerchant code on Carat Portal.< 15 AYES
merchant_usn Identification code of the transaction generated by the merchant.< 12 ANO
order_idOrder code (generated by the merchant)< 40 ANNO
recharge_includedInforms 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 ANO
redirectType 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 ANO
soft_descriptorName of the establishment that will be presented in the credit card invoice. Learn more< 30 ANO
store_cardIndicates 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 ANO
styleInforms 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 ANO
transaction_typeTransaction type that will be performed.

Allowed values:
payment – In case of Payment
preauthorization – In case of Pre-Authorization
Default value – payment
< 32 ANO
payment_linkThis field must receive the value true to activate the payment link functionality.< 5 ANO
additional_dataADDITIONALDATA objectNO
back_urlBACKURL objectNO
iataIATA objectNO
rechargeRECHARGE object.
Contains information related to a recharge transaction.

BACKURL (back_url)#

"url_cancel": "",
"url_failure": "",
"url_success": ""
url_successRedirection URL of the customer in case of success. Must have only the relative path.< 200 ANO
url_failureRedirection URL of the customer in case of failure. Must have only the relative path.< 200 ANO
url_cancelRedirection URL of the customer in case of cancel. Must have only the relative path.< 200 ANO

IATA (iata)#

"departure_tax": "1000",
"first_installment": "20000"
departure_taxDeparture tax amount.< 200 ANO
first_installmentFirst installment value.< 200 ANO

ADDITIONALDATA (additional_data)#

"currency": "BRL",
"method": "",
"postpone_confirmation": "false",
"financing_plan": "",
"payer": { },
"allowed_payment_methods": [],
"max_installments_with_interest": ""
currencyDefault 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 ANO
methodUsed to perform differentiated transactions.

Allowed values:
split – Performs a SPLIT transaction.
< 1024 ANNO
postpone_confirmationAllows the merchant to keep the transaction as Pending Confirmation, and later, confirm or cancel it.< 5 ANO
financing_planFinancing 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 ANNO
max_installmentsMaximum 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 NNO
max_installments_with_interestMaximum 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 NNO
allowed_payment_methodsALLOWED_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.
submerchant_splitSUBMERCHANT_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.
payerPAYER objectNO
mccThe 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 NNO
subacquirer_merchant_idIt is the merchant identification for the subacquirer. This field is used by the sub-merchant funding functionality via SiTef.22 NNO
multiple_payment_methodsIndicates 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/FNO

SUBMERCHANT_SPLIT[] (submerchant_split)#

submerchant_codeBIN/Sipag merchant code< 15 ANNO
submerchant_amountTransaction amount related to the merchant.< 12 NNO

PAYER (payer)#

"store_identification": "card_1",
"identification_number": "123123123"
store_identificationIdentification 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.
< 20NO
identification_numberPayer's identification number.< 1024NO

ALLOWED_PAYMENT_METHODS[] (allowed_payment_methods)#

idIdentifier 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 ANNO

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/['nit']= 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"nsuesitef": "123456789012345",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"

The returned fields are described in table below:

responseCodeCarat Portal response code. Any code different from 0(zero) means failure. Learn more.< 5 N
descriptionResponse description.< 1024 A
urlRedirection URL to begin the payment.< 256 A
nitTransaction identifier on Carat Portal.= 64 A
nsuesitefUSN (Unique Sequential Number) of the transaction on Carat Portal.= 15 A