Transaction creation service
Consuming the transaction creation service is mandatory in both the payment and scheduling flows. As a result of this operation, the merchant will obtain a NIT (payment) which will be necessary for the next steps of the flow, as the utilization of transaction query service.
The NIT have a time limit for their utilization. This deadline is configured on Carat Portal, and if it's exceeded, the transaction will be altered from status NOV (new) to EXP (expired), which blocks further operations with this transaction, making it necessary to consume the transaction creation service again.
Call details#
- Resource:
/v1/transactions - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Examples#
Below are some examples of the transaction creation service call using the cURL tool.
Creating a payment with automatic confirmation#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Creating a payment with late confirmation#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Creating a payment with fraud analysis#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Response codes
See reference on API codes - response codes
Request parameters#
The table below describes the request parameters of the transaction creation service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_usn | Unique sequential number for each order, created by the merchant. The USN will be used during the whole communication with the merchant to help identifying the order. As it is a possible access key on the merchant's side, even though it's optional to Carat Portal, it's strongly recommended that the field is formatted and sent by the merchant's application. | < 12 N | NO |
order_id | Order code defined by the merchant. It's advised that it is different for each order so that it becomes easier to track it. | < 40 AN | NO |
installments | Number of installments. Send 1 for spot sales. | < 2 N | YES |
installment_type | Installment financing type: Value 3 = installments with interest. Value 4 = installments without interest (use this value also on spot sales). Value 6 = installments with interest (IATA). Value 7 = installments without interest (IATA). The IATA financing types are only used by companies that work with air transportation. | < 2 N | YES |
authorizer_id | Code of the authorizer on Carat Portal. Learn more. In operations with tokenized card, if the authorizer code is not informed, the authorizer code used in the card storage will be used. | < 3 N | NO |
amount | Total price of the purchase (in cents). Example: 1,00 = 100 or 1.100,00 = 110000 – send the value without the comma and the dots. | < 12 N | YES |
soft_descriptor | Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more | < 25 AN | NO |
| additional_data | Element for sending additional data. | ||
postpone_confirmation | This field must be sent with value true if a payment with late confirmation is desired. | < 5 T/F | NO |
customer_email | For REST transactions, send the customer receipt to the informed e-mail. | < 50 AN | NO |
| additional_data.payer | Element for sending data related to the payer. | ||
identification_number | Identification document number of the customer (CPF/RG). | < 20 AN | NO |
store_identification | Identification of the customer for card storage. This identification must be unique for each of the merchant's users. But attention, this uniqueness assurance is of total responsibility of the merchant, API Portal won't do any validations. | < 20 AN | YES for scheduling |
| additional_data.merchant | Element for sending data related to the merchant. | ||
email | Merchant's e-mail address. | < 1024 AN | NO |
| additional_data.extra_param.prefixes | Element for sending SiTef prefixes, like CICLOS, CPLANO and VLRADD. If the prefix that was sent is not supported by card, API Portal will invalidate the transaction, preventing that a false impression of the use of a functionality is given. Example: { "key" : "value" } -> { "CICLO" : "01" } | ||
key | Prefix name. | < 1024 AN | NO |
value | Prefix value. | < 1024 AN | NO |
Dynamic MCC Fields#
Request Parameters#
Can be used for Payment and Pre-Authorization REST Transaction creation service#
Additionally to the fields of the REST Transaction Creation Service, the fields below are used specifically in dynamic MCC transactions integrated to the bin routing:
| Parameter | Description | Format | Mandatory | |||
|---|---|---|---|---|---|---|
soft_descriptor | Personalized phrase that will be printed on the bearer's invoice. For information regarding the dynamic MCC, it is equivalent to the name of the submerchant. | < 25 AN | YES | |||
| additional_data | Element for sending additional data. | |||||
mcc | Submerchant's MCC. | = 4 N | YES | |||
subacquirer_merchant_id | Submerchant's code. Deprecated field!!! Use additional_data.subacquirer_merchant.id instead. | < 15 N | NO | |||
| additional_data.subacquirer_merchant | Element for sending data related to a subacquirer's merchant. | |||||
id | Submerchant's code. | < 15 N | YES | |||
phone_number | Submerchant's phone number. | < 14 AN | NO | |||
address | Submerchant's address. | < 48 AN | NO | |||
city | Submerchant's city. | < 13 AN | NO | |||
state | Submerchant's state, in two-digit acronym format (e.g.: SP). | = 2 A | YES | |||
country | Submerchant's country. Follow the standard ISO 3166-1 alpha-2 (e.g.: BR). | = 2 A | YES | |||
zip_code | Submerchant's zip code. | < 9 AN | YES | |||
identification_number | Submerchant's CNPJ. | < 18 N | YES | |||
payment_facilitator_id | Facilitator's code. | < 11 N | YES | |||
Example#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Response parameters#
In case of success, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes de response parameters of the transaction creation service:
| Parameter | Description | Format |
|---|---|---|
code | Carat Portal response code. Any code different from 0 means failure. Learn more. | < 4 N |
message | Carat Portal response message. | < 500 AN |
| payment | ||
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
nit | Payment transaction identifier on Carat Portal. | = 64 AN |
order_id | Order code sent by the merchant on the creation of the transaction. | < 40 AN |
merchant_usn | Unique sequential number sent by the merchant on the creation of the transaction. | < 12 N |
amount | Total price of the purchase specified by the merchant (in cents) on the creation of the transaction. | < 12 N |
| schedule | ||
sid | Schedule transaction identifier on Carat Portal. | = 64 AN |
amount | Amount of the scheduled payments specified by the merchant (in cents) on the creation of the transaction. | < 12 N |
status | Status of the schedule on Carat Portal. Learn more. | = 3 AN |
order_id | Order code sent by the merchant on the creation of the transaction. | < 40 AN |
merchant_usn | Unique sequential number sent by the merchant on the creation of the transaction. | < 12 N |