# Create Transaction Service import ApiDoc from '../../../../../src/components/api-doc/ApiDoc'; ## 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\:///e-sitef-hml/init/[response_type].se | | **Production environment:** | | https\:///e-sitef/init/[response_type].se | > **Attention:** The IP should never be used instead of the domain esitef-ec.softwareexpress.com.br (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](http://json.org)): URL: https\:///e-sitef-hml/init/json.se Basic JSON request example: ```json { "merchant_id": "codigoDaLoja", "amount": "1800" } ``` JSON object `request` with some additional parameters: ```json { "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](https://www.getpostman.com) - Firefox extension: - [RESTClient](http://restclient.net) Sample screens of these tools: [block:image] { "images": [ { "image": [ "https://files.readme.io/871cf076b7211ee16d6c76666d03611ecb2fefe68efed453f528dbba0aabccd0-pagamento-html-postman.png", null, "POSTMAN" ], "align": "center" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/7a6a24ab928a9ef66d47069ef019b33c65666834f19f665b876b2f19ad980a4b-pagamento-html-restclient.png", null, "RESTClient" ], "align": "center" } ] } [/block] ### 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": { } } ``` [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`amount`", "0-1": "Total amount to be paid by the customer.
Format:
Must be sent in cents.
**e.g.:** 1000 (10 dollars).", "0-2": "\\< 12 N", "0-3": "YES", "1-0": "`authenticate`", "1-1": "Parameter informing the need of transaction authentication.
Allowed values:
`0`, `1`, `2`, `3` and `4`.
Default value – `0`
", "1-2": "\\< 1 A", "1-3": "NO", "2-0": "`authorizer_id`", "2-1": "Authorizer code (on Carat Portal)", "2-2": "\\< 10 A", "2-3": "NO", "3-0": "`installments`", "3-1": "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`.", "3-2": "\\< 2 N", "3-3": "NO", "4-0": "`installment_type`", "4-1": "Financing type chosen by the customer.
Allowed values:
`3` – installments with interest
`4` – installments without interest
Default value = `4`.", "4-2": "= 1 N", "4-3": "NO", "5-0": "`merchant_id`", "5-1": "Merchant code on Carat Portal.", "5-2": "\\< 15 A", "5-3": "YES", "6-0": "`merchant_usn `", "6-1": "Identification code of the transaction generated by the merchant.", "6-2": "\\< 12 A", "6-3": "NO", "7-0": "`order_id`", "7-1": "Order code (generated by the merchant)", "7-2": "\\< 40 AN", "7-3": "NO", "8-0": "`recharge_included`", "8-1": "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`", "8-2": "= 5 A", "8-3": "NO", "9-0": "`redirect`", "9-1": "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)", "9-2": "= 1 A", "9-3": "NO", "10-0": "`soft_descriptor`", "10-1": "Name of the establishment that will be presented in the credit card invoice. [Learn more](./soft-descriptor.md)", "10-2": "\\< 30 A", "10-3": "NO", "11-0": "`store_card`", "11-1": "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).", "11-2": "\\< 5 A", "11-3": "NO", "12-0": "`style`", "12-1": "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.", "12-2": "= 1 A", "12-3": "NO", "13-0": "`transaction_type`", "13-1": "Transaction type that will be performed.

Allowed values:
`payment` – In case of Payment
`preauthorization` – In case of Pre-Authorization
Default value – `payment`", "13-2": "\\< 32 A", "13-3": "NO", "14-0": "`payment_link`", "14-1": "This field must receive the value `true` to activate the payment link functionality.", "14-2": "\\< 5 A", "14-3": "NO", "15-0": "`additional_data`", "15-1": "**ADDITIONALDATA** object", "15-2": "", "15-3": "NO", "16-0": "`back_url`", "16-1": "**BACKURL** object", "16-2": "", "16-3": "NO", "17-0": "`iata`", "17-1": "**IATA** object", "17-2": "", "17-3": "NO", "18-0": "`recharge`", "18-1": "**RECHARGE** object.
Contains information related to a recharge transaction.", "18-2": "", "18-3": "NO" }, "cols": 4, "rows": 19, "align": [ null, null, null, null ] } [/block] #### BACKURL (`back_url`) ``` { "url_cancel": "https://cancel.com", "url_failure": "https://failure.com", "url_success": "https://success.com" } ``` [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`url_success`", "0-1": "Redirection URL of the customer in case of success. Must have only the relative path.", "0-2": "\\< 200 A", "0-3": "NO", "1-0": "`url_failure`", "1-1": "Redirection URL of the customer in case of failure. Must have only the relative path.", "1-2": "\\< 200 A", "1-3": "NO", "2-0": "`url_cancel`", "2-1": "Redirection URL of the customer in case of cancel. Must have only the relative path.", "2-2": "\\< 200 A", "2-3": "NO" }, "cols": 4, "rows": 3, "align": [ null, null, null, null ] } [/block] #### IATA (`iata`) ``` { "departure_tax": "1000", "first_installment": "20000" } ``` [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`departure_tax`", "0-1": "Departure tax amount.", "0-2": "\\< 200 A", "0-3": "NO", "1-0": "`first_installment`", "1-1": "First installment value.", "1-2": "\\< 200 A", "1-3": "NO" }, "cols": 4, "rows": 2, "align": [ null, null, null, null ] } [/block] #### ADDITIONALDATA (`additional_data`) ``` { "currency": "BRL", "method": "", "postpone_confirmation": "false", "financing_plan": "", "payer": { }, "allowed_payment_methods": [], "max_installments_with_interest": "" } ``` [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`currency`", "0-1": "Default currency used for all the items in the purchase.
Currency code according to the [ISO 4217](http://pt.wikipedia.org/wiki/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.", "0-2": "= 3 A", "0-3": "NO", "1-0": "`method`", "1-1": "Used to perform differentiated transactions.

Allowed values:
`split` – Performs a **SPLIT** transaction.", "1-2": "\\< 1024 AN", "1-3": "NO", "2-0": "`postpone_confirmation`", "2-1": "Allows the merchant to keep the transaction as Pending Confirmation, and later, confirm or cancel it.", "2-2": "\\< 5 A", "2-3": "NO", "3-0": "`financing_plan`", "3-1": "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.", "3-2": "\\< 4 AN", "3-3": "NO", "4-0": "`max_installments`", "4-1": "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**.", "4-2": "\\< 3 N", "4-3": "NO", "5-0": "`max_installments_with_interest`", "5-1": "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**.", "5-2": "\\< 2 N", "5-3": "NO", "6-0": "`allowed_payment_methods`", "6-1": "**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.](#allowed_payment_methods-allowed_payment_methods)", "6-2": "", "6-3": "NO", "7-0": "`mcc`", "7-1": "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.", "7-2": "4 N", "7-3": "NO", "8-0": "`subacquirer_merchant_id`", "8-1": "It is the merchant identification for the subacquirer. This field is used by the sub-merchant funding functionality via SiTef.", "8-2": "22 N", "8-3": "NO", "9-0": "`multiple_payment_methods`", "9-1": "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.", "9-2": "\\< 5 T/F", "9-3": "NO" }, "cols": 4, "rows": 10, "align": [ null, null, null, null ] } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`store_identification`", "0-1": "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.", "0-2": "\\< 20", "0-3": "NO", "1-0": "`identification_number`", "1-1": "Payer's identification number.", "1-2": "\\< 1024", "1-3": "NO" }, "cols": 4, "rows": 2, "align": [ null, null, null, null ] } [/block] #### ALLOWED_PAYMENT_METHODS\[] (`allowed_payment_methods`) ``` [ { "id":"CRD" }, { "id":"DBT" }, { "id":"WLT" } ] ``` [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`id`", "0-1": "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.", "0-2": "\\< 3 AN", "0-3": "NO" }, "cols": 4, "rows": 1, "align": [ null, null, null, null ] } [/block] > **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](portal-lojista-configuracao-autorizadora.md). > > **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: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "0-0": "`responseCode`", "0-1": "Carat Portal response code. Any code different from `0`(zero) means failure. [Learn more.](codigos-da-api.md#response-codes)", "0-2": "\\< 5 N", "1-0": "`description`", "1-1": "Response description.", "1-2": "\\< 1024 A", "2-0": "`url`", "2-1": "Redirection URL to begin the payment.", "2-2": "\\< 256 A", "3-0": "`nit`", "3-1": "Transaction identifier on Carat Portal.", "3-2": "= 64 A", "4-0": "`nsuesitef`", "4-1": "USN (Unique Sequential Number) of the transaction on Carat Portal.", "4-2": "= 15 A" }, "cols": 3, "rows": 5, "align": [ null, null, null ] } [/block]