Transaction Creation

Brazil

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

curl 
--request POST "https://{{url}}/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "12042142155",
    "merchant_usn": "12042142155",
    "amount": "1000"
  }
}

Creating a payment with late confirmation

Request:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request POST "https://{{url}}/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
   "merchant_usn":"12050620649",
   "order_id":"12050620649",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000",
   "additional_data":{
      "postpone_confirmation":"true"
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "12050620649",
    "merchant_usn": "12050620649",
    "amount": "1000"
  }
}

Creating a payment with fraud analysis

Request:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request POST "https://{{url}}/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header “merchant_key: xxxxxxxxxxx”
--data-binary
{
   "merchant_usn":"12042142155",
   "order_id":"12042142155",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000",
   "additional_data":{
      "payer":{
         "name":"Comprador",
         "surname":"credito AF",
         "email":"[email protected]",
         "city":"Rio de Janeiro",
         "state":"RJ",
         "address_street_name":"Rua Jupiter",
         "address_street_number":"174",
         "address_zip_code":"21241140",
         "born_date":"1991-01-02T08:30:00",
         "address_street_complement":"AP 201",
         "address_country":"BRA"
      },
      "shipment":{
         "method":"LOW_COST",
         "name":"Sr Comprador Teste",
         "phones":[
            {
               "number":"21114740",
               "ddd":"16",
               "ddi":"55"
            }
         ],
         "receiver_address":{
            "complement":"AP 201",
            "city":"Rio de Janeiro",
            "state":"RJ",
            "country":"BRA",
            "zip_code":"21241140",
            "street_number":"174",
            "street_name":"Rua Jupiter"
         }
      },
      "connections":[
         {
            "from":"RAO",
            "to":"SAO",
            "flight_date":"2020-01-02T20:15:00"
         }
      ],
      "gift":"false",
      "browser":{
         "email":"[email protected]",
         "agent":"Chrome",
         "cookies_accepted":"false",
         "host_name":"Teste",
         "ip_address":"200.190.150.350"
      },
      "items":[
         {
            "title":"ItemTeste",
            "quantity":"1",
            "id":"1487337308522",
            "risk":"HIGH",
            "hedge":{
               "time":"NORMAL",
               "host":"OFF",
               "nonSensical":"OFF",
               "obscenities":"OFF",
               "phone":"OFF",
               "velocity":"HIGH"
            },
            "passenger":{
               "name":"Comprador accept",
               "email":"[email protected]",
               "rating":"ADULT",
               "phone":{
                  "number":"999994444",
                  "ddd":"11",
                  "ddi":"55"
               },
               "legal_document":"1234567890",
               "customer_class":"Gold"
            },
            "unit_price":"1000",
            "category_id":"other",
            "gift_category":"OFF"
         }
      ],
      "extra_param":{
         "acquirer_params":[
            {
               "key":"95",
               "value":"parametros adicionais"
            }
         ]
      },
      "anti_fraud":"enabled_before_auth",
      "anti_fraud_institution":"AUTHORIZER",
      "anti_fraud_criteria":"ALWAYS",
      "finger_print_id":"074c1ee676ed4998ab66491013c565e2",
      "returns_accepted":"true",
      "journey_type":"OUTWARD"
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "12042142155",
    "merchant_usn": "12042142155",
    "amount": "1000"
  }
}

Request parameters

The table below describes the request parameters of the transaction creation service:

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

Updated 6 days ago

Did this page help you?