Create transaction service
#
Transaction creation processThe 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://sandbox.ecomm-bin.fiserv.com.br/e-sitef-hml/init/[response_type].se |
Production environment: |
https://ecomm-bin.fiserv.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 sandbox.ecomm-bin.fiserv.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
orxml
;
JSON request example (JavaScriptObjectNotation):
URL: https://sandbox.ecomm-bin.fiserv.com.br/e-sitef-hml/init/json.se
Basic JSON request example:
JSON object request
with some additional parameters:
#
Test toolsFor initial testing in this interface, if necessary, some tools can be used in order to better understand REST communication:
- Application for Windows/Linux/Mac:
- Firefox extension:
Sample screens of these tools:
#
Request parametersThe 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.
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:
1 . | < 2 N | NO |
installment_type | Financing type chosen by the customer. Allowed values: 3 – installments with interest4 – 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 Paymentpreauthorization – In case of Pre-AuthorizationDefault 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 |
back_url
)#
BACKURL (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 (Parameter | Description | Format | Mandatory |
---|---|---|---|
departure_tax | Departure tax amount. | < 200 A | NO |
first_installment | First installment value. | < 200 A | NO |
additional_data
)#
ADDITIONALDATA (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 – RealVEF – Venezuelan bolívar fuerteUSD – American DollarGBP – PoundAmong 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[] (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
andinstallment_type
fields without theauthorizer_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
, andinstallment_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 parametersThe response of the transaction creation operation (JSON format):
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 |