Quick start

This guide shows the process of executing a pre-authorization, using Carat Portal's REST web service interface.

Requirements#

Active account on Carat Portal's homologation environment (obtained with our support team)
A tool capable of performing HTTP calls, such as Postman, REST Client or cURL

Creating the Pre-Authorization#

HTTP method: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions

Headers:

Content-Type: application/json
merchant_id: {your merchant id}
merchant_key: {your merchant key}

Request:

To use this example, remember to set the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
  "order_id": "orderID",
  "merchant_usn": "20190101",
  "amount": "100",
  "transaction_type": "preauthorization"
}

curl
--request POST "https://{{url}}/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "order_id":"orderID",
    "merchant_usn":"20190101",
    "amount":"100",
    "transaction_type":"preauthorization"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "pre_authorization": {
    "status": "NOV",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "orderID",
    "merchant_usn": "20190101",
    "amount": "100"
  }
}

Learn more about this service.

Pre-Authorization#

HTTP Method: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/<nit>

Headers:

Content-Type: application/json
merchant_id: {your merchant id}
merchant_key: {your merchant key}

Request:

To use this example, remember to set the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
  "authorizer_id": "2",
  "installments": "2",
  "installment_type": "4",
  "card": {
    "number": "xxxxxxxxxxxxxxxx",
    "expiry_date": "1222",
    "security_code": "123"
  }
}

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1222",
        "security_code":"123"
    }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "pre_authorization": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK.",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "customer_receipt": "=== CUSTOMER RECEIPT ===",
    "merchant_receipt": "=== MERCHANT RECEIPT ===",
    "authorizer_id": "2",
    "authorizer_date": "09/11/2018T19:40",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorization_number": "013245",
    "merchant_usn": "20190101",
    "esitef_usn": "181109017689784",
    "order_id": "orderID",
    "sitef_usn": "212194",
    "host_usn": "999212194",
    "amount": "100",
    "issuer": "2",
    "payment_type": "C",
    "authorizer_merchant_id": "000000000000000"
  }
}

Learn more about this service.

Capturing the pre-authorization#

HTTP Method: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/capture/<nit>

Headers:

Content-Type: application/json
merchant_id: {your merchant id}
merchant_key: {your merchant key}

Request:

To use this example, remember to set the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
  "amount": "100",
  "installments": "1",
  "installment_type": "4",
  "card": {
    "number": "xxxxxxxxxxxxxxxx",
    "expiry_date": "1222",
    "security_code": "123"
  },
  "acquirer": {
    "submerchant_split": [
      {
        "submerchant_code": "empresa01",
        "submerchant_amount": "10"
      },
      {
        "submerchant_code": "empresa02",
        "submerchant_amount": "20"
      },
      {
        "submerchant_code": "empresa03",
        "submerchant_amount": "20"
      },
      {
        "submerchant_code": "empresa04",
        "submerchant_amount": "30"
      },
      {
        "submerchant_code": "empresa05",
        "submerchant_amount": "30"
      }
    ]
  }
}

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "amount":"100",
    "installments":"1",
    "installment_type":"4",
    "card":{
    "number":"xxxxxxxxxxxxxxxx",
    "expiry_date":"1222",
    "security_code":"123"
    },
    "acquirer":{
        "submerchant_split":[
            {
                "submerchant_code":"empresa01",
                "submerchant_amount":"10"
            },
            {
                "submerchant_code":"empresa02",
                "submerchant_amount":"20"
            },
            {
                "submerchant_code":"empresa03",
                "submerchant_amount":"20"
            },
            {
                "submerchant_code":"empresa04",
                "submerchant_amount":"30"
            },
            {
                "submerchant_code":"empresa05",
                "submerchant_amount":"30"
            }
        ]
    }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "capture": {
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "orderID",
    "customer_receipt": "=== CUSTOMER RECEIPT ===",
    "merchant_receipt": "=== MERCHANT RECEIPT ===",
    "authorizer_id": "2",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK.",
    "authorizer_date": "11/08/2019T14:17",
    "authorizer_merchant_id": "000000000000000",
    "authorization_number": "212195",
    "esitef_usn": "180921015287704",
    "merchant_usn": "20190101",
    "sitef_usn": "212195",
    "host_usn": "999212195",
    "amount": "100",
    "payment_type": "C",
    "issuer": "2"
  }
}

Learn more about this service.

Card Query#

HTTP method: POST

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/<nit>/cards

Headers:

Content-Type: application/json
merchant_id: {your merchant id}
merchant_key: {your merchant key}

Request:

To use this example, remember to set the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

{
  "card": {
    "number": "5555555555555555"
  },
  "authorizer_id": "1"
}

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "card":{
        "number":"5555555555555555"
    },
    "authorizer_id":"1"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "preauthorization": {
    "status": "NOV"
  },
  "card": {
    "acquirer_name": "Bin",
    "authorizer_id": "1",
    "authorizer_response_code": "000",
    "is_customer_id_required": "false",
    "is_expiry_date_required": "true",
    "is_installment_funding_enabled": "true",
    "is_security_code_required": "true",
    "is_spot_sale_enabled": "true",
    "is_with_interest_sale_enabled": "true",
    "is_without_interest_sale_enabled": "true",
    "max_installments_with_interest": "12",
    "min_installments_with_interest": "01",
    "prefixes": {
      "TRAT": "2",
      "PERIFERICO": "1",
      "CSEG": "2"
    }
  }
}

Learn more about this service.

Transaction Query#

HTTP method: GET

URL: https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transaction/<nit>

Headers:

Content-Type: application/json
merchant_id: {your merchant id}
merchant_key: {your merchant key}

Request:

To use this example, remember to set the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

curl
--request GET "https://{{url}}/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "pre_authorization": {
    "acquirer_id": "1181",
    "acquirer_name": "GetNet Lac",
    "amount": "1470",
    "authorization_number": "301367",
    "authorizer_code": "000",
    "authorizer_date": "30/10/2018T11:58",
    "authorizer_id": "1",
    "authorizer_merchant_id": "000000000000000",
    "authorizer_message": "Transacao OK",
    "customer_receipt": "=== CUSTOMER RECEIPT ===",
    "merchant_receipt": "=== MERCHANT RECEIPT ===",
    "esitef_usn": "181030016873984",
    "host_usn": "010301367   ",
    "issuer": "1",
    "merchant_usn": "20180809",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "201808020001",
    "payment_type": "C",
    "sitef_usn": "301367",
    "status": "CON"
  },
  "capture": {
    "acquirer_id": "1181",
    "acquirer_name": "GetNet Lac",
    "amount": "1380",
    "authorization_number": "000000",
    "authorizer_date": "30/10/2018T12:00",
    "authorizer_id": "1",
    "customer_receipt": "=== CUSTOMER RECEIPT ===",
    "merchant_receipt": "=== MERCHANT RECEIPT ===",
    "esitef_usn": "181030016874034",
    "host_usn": "010301368   ",
    "issuer": "1",
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK SDO DISPONIVEL          244,00",
    "merchant_usn": "20180809",
    "nit": "abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr1234567890",
    "order_id": "201808020001",
    "authorizer_merchant_id": "000000000000000",
    "payment_type": "C",
    "sitef_usn": "301368",
    "status": "CON"
  }
}

Learn more about this service.

Home

Requirements#

Creating the Pre-Authorization#

Pre-Authorization#

Capturing the pre-authorization#

Card Query#

Transaction Query#