Payments

Payments Documentation (LATAM)

Payments
Payments - V1 Double Request
Payments - V2 Single Request

Payments

_{Source: https://docs.apis-fiserv.com/latam/docs/payments}

Brazil

Overview

Carat Portal has two interfaces for integration with the virtual store, HTTPS POST and HTTPS Web Services, enabling the proper way of interaction between the merchant and Carat Portal, according to the programming language and the platform of the virtual store.

On the REST Web Service interface, the payment and card data will be collected by the merchant and Carat Portal will only make the payment with the financial institution.

This interface provides payments with credit, debit or voucher cards. For payments such as electronic transfer or boleto, the POST/HTML interface must be used instead.

And to learn more about these nomenclatures (Bin, Software Express, Carat, e-Sitef) Learn more

Communication

To make a Web Service transaction, the whole communication must be done via HTTPS/TLS. It's important that the merchant's server supports encryption of a minimum of 128 bits. The merchant's server must make calls on specific addresses to do REST transactions.

Each service must be called using the base URL concatenated with the desired resource (see the chapter related to the service to be consumed). The HTTP method (GET, POST or PUT) indicates the expected action on the selected resource. Listed below are the base URLs of Carat Portal:

Production base URL:

https:///e-sitef/api

Homologation base URL:

https:///e-sitef/api

Every call received by the services will be responded synchronously.

Attention:

Never use the IP instead of the domain. The IP can change at any time without previous warning, so it's important to use the domain when accessing Carat Portal.

Important:

Besides the response parameters of the services described in this specification, Carat Portal can return other parameters without previous warning.

It's important that the application is prepared to receive the unknown parameters besides the fields already specified and simply ignore them.

Flow

The payment flow will be initiated by the merchant's application after the customer completes the purchase and sends the payment data.

There are two types of payment flow: with automatic confirmation, where Carat Portal is responsible for confirming the payment with the acquirer; and with late confirmation, where the merchant's application is responsible for confirming the payment by consuming the confirmation service.

The late confirmation is usually used when the merchant's application allows paying with more than one card or when some validation is done before confirming the payment.

Payment with automatic confirmation

Flow description:

The merchant creates a transaction via API passing information such as the merchant ID, number of installments and the order ID and obtains as response a NIT (Transaction Identifier Number).
The merchants then proceeds consuming the payment effectuation service, passing the NIT and the customer's card data. In case of success, the payment transaction will change its status to CON (confirmed).

Example

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

Request:

curl --location 'https://{{url}}/e-sitef/api/v2/payments/' --header 'Content-Type: application/json' --header 'merchant_id: xxxxxxxxx' --header 'merchant_key: xxxxxxxxxxxxxx' --data '{
    "merchant_usn": "12050620649",
   "order_id":"1686591679260",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "1100",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555",
        "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
        "wallet_type": "network_token"
    }
}'

Response: (note the transaction status, that is CON of Confirmed)

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "APROVADA",
        "status": "CON",
        "nit": "dc8a370d394e3868de756b53b912a3b41cffdf28e26bff405ddb20737bce5e06",
        "order_id": "1686591679260",
        "customer_receipt": "==== customer receipt ====",
        "merchant_receipt": "==== merchant receipt ====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "12/06/2023T14:41",
        "authorization_number": "000026",
        "merchant_usn": "12050620649",
        "esitef_usn": "230612015722270",
        "sitef_usn": "000026",
        "host_usn": "006000026   ",
        "amount": "1100",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000000",
        "terminal_id": "ES000001",
        "payment_date": "12/06/2023T14:41",
        "recurrency_tid": "999988887777666"
    }
}

Payment with late confirmation

Flow description:

As in the payment flow with automatic confirmation, the merchant creates a transaction via API passing the payment data. In addition, they must send the postpone_confirmation parameter with the value true.
The merchant then proceeds consuming the payment effectuation service, passing the NIT and the customer's card data. In case of success, the payment transaction will change its status to PPC (pending payment confirmation).
Concluding, the merchant calls the payment confirmation service, passing the NIT again and the parameter confirm with value true, resulting in a transaction with status CON (confirmed). There is also the possibility for the merchant to undo de transaction instead of confirming. For this, the confirm parameter must be sent with the value false, which will result in a transaction with status PPN (undone).

Exemplo

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

Note the parameter postpone_confirmation included with true value, and the transaction status that now is PPC.

curl --location 'https://{{url}}/e-sitef/api/v2/payments/' --header 'Content-Type: application/json' --header 'merchant_id: xxxxxxxxx' --header 'merchant_key: xxxxxxxxxxxxxx' --data '{
    "merchant_usn": "12050620649",
   "order_id":"1686592079260",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "1100",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555",
        "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
        "wallet_type": "network_token"
    },
    "additional_data": {
        "postpone_confirmation": "true"
    }
}'

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "APROVADA",
        "status": "PPC",
        "nit": "7321992585edcd4683b3a242426cb30f9a1643dbcea634a55ae81599d8ea5081",
        "order_id": "1686592079260",
        "customer_receipt": " ==== customer receipt ====",
        "merchant_receipt": " ==== merchant receipt ====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "12/06/2023T14:48",
        "authorization_number": "000027",
        "merchant_usn": "12050620649",
        "esitef_usn": "230612015722290",
        "sitef_usn": "000027",
        "host_usn": "006000027   ",
        "amount": "1100",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000000",
        "terminal_id": "ES000001",
        "payment_date": "12/06/2023T14:48",
        "recurrency_tid": "999988887777666"
    }
}

Payments - V1 Double Request

Quick Start

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-quickstart}

Brazil

This guide shows the process of performing a spot sale payment, using Carat Portal's REST web service interface.

What you'll need

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 transaction

HTTP method: POST

URL: https:///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, don't forget to define the variable {{url}} to 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":"1"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV",
    "nit": "

Learn more about this service.

Paying

HTTP method: POST

URL: https:///e-sitef/api/v1/payments/

Replace the field in the URL above with the NIT obtained in the transaction creation step.

Headers:

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

Request:

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/payments/

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "

Learn more about this service.

Checking the payment status

HTTP method: GET

URL: https:///e-sitef/api/v1/transactions/

Replace the field in the URL above with the NIT obtained in the transaction creation step.

Headers:

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

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

curl
--request GET "https://{{url}}/e-sitef/api/v1/transactions/

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "

Learn more about this service.

Transaction Creation

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-begin}

Brazil

import ResponseCodes from './codigos-de-resposta.md';
import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

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) and/or a SID (schedule) which will be necessary for the next steps of the flow, as the utilization of transaction query service.

The NIT and the SID 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 schedule

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: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12053724147",
   "order_id":"12053724147",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1000",
   "schedule":{
      "amount":"900",
      "initial_date":"03/08/2017",
      "number_of_times":"3",
      "interval":"1",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "additional_data":{
      "payer":{
         "store_identification":"98253053045"
      }
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "12053724147",
    "merchant_usn": "12053724147",
    "amount": "1000"
  },
  "schedule": {
    "status": "NOV",
    "sid": "qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
    "amount": "900",
    "order_id": "12053724147",
    "merchant_usn": "12053724147"
  }
}

Creating a schedule without payment

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: xxxxxxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12055523043",
   "order_id":"12055523043",
   "authorizer_id":"2",
   "schedule":{
      "amount":"900",
      "do_payment_now":"false",
      "initial_date":"03/08/2017",
      "number_of_times":"3",
      "interval":"1",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "additional_data":{
      "payer":{
         "store_identification":"98253053045"
      }
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "schedule": {
    "status": "NOV",
    "sid": "qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
    "amount": "900",
    "order_id": "12055523043",
    "merchant_usn": "12055523043"
  }
}

Creating a payment with Cielo e-Commerce 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":"

Response:

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

Creating a payment with risk analysis (using Konduto antifraud)

For further information, please refer to our specific Konduto section.

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":"2423423434",
   "order_id":"2432342343",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"1300",
   "additional_data":{
      "anti_fraud":"enabled_before_auth",
      "visitor_id":"XKhas09jcks",
      "items":[
         {
            "title":"title1",
            "quantity":"1",
            "unit_price":"1111",
            "description":"description1",
            "id":"id1",
            "discount_amount":"111",
            "sku":"sku1",
            "creation_date":"11/01/2011"
         }
      ],
      "payer":{
         "name":"Marcos",
         "surname":"da Silva",
         "email":"

Response:

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

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. If the merchant's integration with the acquirers (Cielo, Rede, etc) is with Carat Portal and SiTef, the order_id field that has a maximum length of 40 characters, will be reduced to 12 characters, due to a restriction on SiTef. This reduction will be done maintaining the characters from left to right (example: if the inserted order ID is 12345678901234567890 on Carat Portal, on SiTef it will be only 123456789012).	< 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

curl 
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "merchant_usn": "19035815234",
  "order_id": "1616438400044",
  "installments": "1",
  "installment_type": "4",
  "authorizer_id": "2",
  "amount": "1300",
  "soft_descriptor": "L012121",
  "additional_data": {
    "mcc": "1111",
    "subacquirer_merchant": {
      "id": "12345",
      "address": "Avenida Paulista, 2000",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "zip_code": "01107001",
      "identification_number": "53455823000178",
      "payment_facilitator_id": "654321",
      "phone_number": "+55 11 99999-9999"
    }
  }
}

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "status": "NOV",
        "nit": "6215a32a557f5dc4627b540f517e40abd6a8411cf89a2e073913aa25d7c95590",
        "order_id": "1616438400044",
        "merchant_usn": "19035815234",
        "amount": "1300"
    }
}

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. If the merchant's integration with the acquirers (Cielo, Rede, etc) is with Carat Portal and SiTef, the order_id field that has a maximum length of 40 characters, will be reduced to 12 characters, due to a restriction on SiTef. This reduction will be done maintaining the characters from left to right (example: if the inserted order ID is 12345678901234567890 on Carat Portal, on SiTef it will be only 123456789012).	< 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	< 30 AN	NO
`authorizer_authentication`	This field must be sent with value `true` if a payment with authentication is desired. This functionality is only available to Cielo e-Commerce and e.Rede REST.	< 5 T/F	NO
`encrypted_card`	This field must be sent with value `true` if the card number to be sent in the step of the flow uses SiTef's encryption. The option to send the encrypted card will only be possible with a SiTef routing and it's necessary to pre-configure the SiTef used by the merchant accordingly.	< 5 T/F	NO
iata	This element contains specific fields for IATA transactions.
`departure_tax`	Departure tax in cents.	< 12 N	YES only for installment_type = 6 or 7
`first_installment`	Amount of the first installment on IATA transactions in cents. This functionality is available only for GetNet acquirer.	< 12 N	NO
schedule Sending the `schedule` element implies on using the schedule functionality. None of its fields are mandatory if making a simple payment only is desired.
`amount`	Amount in cents of the recurrent payments. If this field is not sent, the payment amount will be used.	< 12 N	YES
`initial_date`	Execution date of the first scheduled payment. This date must have at least two days ahead of the current day and the days 29, 30 and 31 are never allowed. The date format to be followed is: `DD/MM/YYYY` Example: 20/04/2021	= 10 D	YES
`number_of_times`	Number of scheduled payments to be executed. If this field is not sent, the schedule will be active infinitely.	< 3 N	NO
`interval`	Interval in months between each scheduled payment. If this field is not sent, the value `1` will be used (monthly executions).	< 2 N	NO
`do_payment_now`	Send this field with the value `false` if a schedule without immediate payment is desired. If this field is absent or any value other than `false`, a schedule with immediate payment will be created.	< 5 T/F	NO
`installments`	Number of installments of each scheduled payment. If this field is not sent, the value `1` will be used.	<2 N	NO
`installment_type`	Installment financing type of the scheduled payments: Value `3` = installments with interest. Value `4` = installments without interest (use this value also on spot sales). If this field is not sent, the value `4` will be used.	< 2 N	NO
`soft_descriptor`	Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more	< 30 AN	NO
`show_times_invoice`	For finite time schedules, send this field with value `true` if you want to add at the end of the `soft_descriptor` field the current times/number of times (e.g. Subscription 3/12).	< 5 T/F	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
`financing_plan`	Financing Plan code used for Via Certa Financiadora routed payments, only in case of installments plan with interest.	< 4 N	COND.
`ecomm_pos_ref`	This field will send and identification that will appear in the PDV field of the SiTef Web report for e-commerce transactions.	< 8 AF	NO
additional_data.payer	Element for sending data related to the payer.
`customer_email`	If informed, it must be an e-mail to send the receipt to the consumer, when a transaction is effectuated via REST.	< 50 AN	NO
`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

The table below describes the additional parameters that must be sent on a payment with fraud analysis (for the time being only available for Cielo e-Commerce):

Parameter	Description	Format	Mandatory
additional_data
`anti_fraud_institution`	This field is used when there is no contract with an anti-fraud analysis institution and an anti-fraud analysis done by an authorizer is desired, in that case the value 'AUTHORIZER'must be input. If you have a contract with a anti-fraud analysis institution such as: Konduto, CyberSource and ClearSale, this field should not be used.	= 10 AN	COND.
`anti_fraud`	Enables the fraud analysis service. Allowed values: `enabled_before_auth` – fraud analysis will be done BEFORE the payment authorization. If the analysis is rejected, the payment won't be initiated. `enabled_after_auth` – fraud analysis will be done AFTER the payment authorization. If the analysis is rejected, the payment will be cancelled.	< 19 AN	YES para análise de fraude
`anti_fraud_criteria`	Criteria for fraud analysis execution. Allowed values: `ON_SUCCESS` – only perform the analysis if the transaction had succeeded. `ALWAYS` – always perform the analysis.	< 10 AN	NO
`finger_print_id`	Identifier used to cross information obtained by the internet user's Browser with the data sent for analysis. This same value must be passed in the SESSIONID variable of the DeviceFingerPrint script. Further details can be found on http://apidocs.braspag.com.br/#CriandoumavendacomAnalisedeFraude.	< 50 AN	NO
`gift`	Boolean that indicates whether the order is a gift or not.	< 5 T/F	NO
`returns_accepted`	Boolean that defines whether returns are accepted for this order.	< 5 T/F	NO
`journey_type`	Type of the trip. Allowed values: `ROUND_TRIP` – round trip. `OUTWARD` – outward. `RETURN` – return.	< 10 AN	NO
additional_data.payer
`name`	Name of the customer. Note: the concatenation of name and surname must not surpass 255 characters.	< 200 AN	NO
`surname`	Surname of the customer. Note: the concatenation of name and surname must not surpass 255 characters.	< 200 AN	NO
`email`	E-mail of the customer.	< 255 AN	NO
`born_date`	Birthdate of the costumer, in `YYYY-MM-DDTHH:MM:SS` format. E.G.: 1991-01-02T08:30:00.	= 19 AN	NO
`adress_street_name`	Address street name of the customer.	< 255 AN	NO
`adress_street_number`	Address street number of the customer.	< 15 AN	NO
`adress_street_complement`	Address complement of the customer.	< 50 AN	NO
`adress_zip_code`	Zip code of the customer. E.G.: 21241140.	< 9 AN	NO
`city`	City of the customer.	< 50 AN	NO
`state`	State of the customer. E.G.: SP.	= 2 AN	NO
`address_country`	Country of the customer, following ISO 3166-1. Ex.: BRA.	< 35 AN	NO
additional_data.shipment.receiver_address
`street_name`	Shipment address street name.	< 255 AN	NO
`street_number`	Shipment address street number.	< 15 AN	NO
`complement`	Shipment address complement.	< 50 AN	NO
`zip_code`	Shipment zip code. E.G.: 21241-140.	< 9 AN	NO
`city`	Shipment city.	< 50 AN	NO
`state`	Shipment state.	= 2 AN	NO
`country`	Shipment country, following ISO 3166-1. E.G.: BRA	= 3 AN	NO
additional_data.browser
`cookies_accepted`	Boolean to identify whether the customer's browser accepts cookies. Send `true` if positive.	< 5 T/F	NO
`email`	Email registered in the customer's browser.	< 100 AN	NO
`host_name`	Host name where the customer was before entering the store's website.	< 60 AN	NO
`ip_address`	Customer's IP address. It is strongly recommended sending this field.	< 15 AN	NO
`agent`	Name of the browser used by the customer. E.G.: Chrome.	< 40 AN	NO
additional_data.items[]
`gift_category`	Field that will evaluate the billing and delivery addresses for different cities, states or countries. Allowed values: `OFF` – Ignores fraud analysis for divergent addresses. `YES` – In case of divergence between billing and delivery addresses, mark with small risk. `NO` – In case of divergence between billing and delivery addresses, mark with high risk.	< 3 AN	NO
`risk`	Product risk level. Allowed values: `LOW` – The product has a history of few chargebacks. `NORMAL` – The product has a history of chargebacks considered normal. `HIGH` – The product has a history of chargebacks above average.	< 6 AN	NO
`title`	Product name.	< 255 AN	NO
`quantity`	Quantity of the product to be acquired.	< 15 N	NO
`id`	Product identifier.	< 255 AN	NO
`unit_price`	Unit price of the product.	< 15 N	NO
`category_id`	Product type. Allowed values: `art`, `baby`, `coupon`, `donation`, `computing`, `camera`, `video_game`, `television`, `car_electronic`, `electronic`, `automotive`, `entertainment`, `fashion`, `game`, `home`, `musical`, `phone`, `service`, `learning`, `ticket`, `travel`, `virtual_good`, `physical`, `other`, `adult_content`, `gift_certificate`, `handling`, `shipping`, `shipping_and_handling` ou `subscription`.	< 21 AN	NO
additional_data.items[].hedge
`time`	Level of importance of client order day time. Allowed values: `LOW` – Low importance in the time of day when the purchase was made, for the fraud analysis. `NORMAL` – Normal importance in the time of day when the purchase was made, for the fraud analysis. `HIGH` – High importance in the time of day when the purchase was made, for the fraud analysis. `OFF` – Purchase time does not affect fraud analysis.	< 6 AN	NO
`host`	Level of importance of email and IP addresses of clients at scoring risk. Allowed values: `LOW` – Low importance of e-mail and IP address in fraud analysis. `NORMAL` – Normal importance of e-mail and IP address in fraud analysis. `HIGH` – High importance of e-mail and IP address in fraud analysis. `OFF` – E-mail and IP address do not affect fraud analysis.	< 6 AN	NO
`non_sensical`	Level of testing performed on buyer data with meaningless received orders. Allowed values: `LOW` – Low importance of the verification made on the buyer's order, in fraud analysis. `NORMAL` – Normal importance of the verification made on the buyer's order, in fraud analysis. `HIGH` – High importance of the verification made on the buyer's order, in fraud analysis. `OFF` – Verification of buyer's order does not affect fraud analysis.	< 6 AN	NO
`obscenities`	Level of obscenity of received orders. Allowed values: `LOW` – Low importance of obscenity verification of buyer's order, in fraud analysis. `NORMAL` – Normal importance of obscenity verification of buyer's order, in fraud analysis. `HIGH` – High importance of obscenity verification of buyer's order, in fraud analysis. `OFF` – Obscenity verification of buyer's order does not affect fraud analysis.	< 6 AN	NO
`phone`	Level of tests performed with telephone numbers. Allowed values: `LOW` – Low importance on tests performed with telephone numbers. `NORMAL` – Normal importance on tests performed with telephone numbers. `HIGH` – High importance on tests performed with telephone numbers. `OFF` – Phone number tests do not affect fraud analysis.	< 6 AN	NO
`velocity`	Level of importance of customer purchase frequency. Allowed values: `LOW` – Low importance in the number of purchases made by the client in the last 15 minutes. `NORMAL` – Normal importance in the number of purchases made by the client in the last 15 minutes. `HIGH` – High importance in the number of purchases made by the client in the last 15 minutes. `OFF` – The frequency of purchases made by the client does not affect the fraud analysis.	< 6 AN	NO
additional_data.items[].passenger
`email`	Passenger email.	< 255 AN	NO
`legal_document`	Id of the passenger to whom the ticket was issued.	< 32 AN	NO
`name`	Passenger name.	< 120 AN	NO
`rating`	Passenger classification. Allowed values: `ADULT` – Adult passenger. `CHILD` – Child passenger. `INFANT` – Infant passenger. `YOUTH` – Teenage passenger. `STUDENT` – Student passenger. `SENIOR_CITIZEN` – Elderly passenger. `MILITARY` – Military passenger.	< 14 AN	NO
`customer_class`	Classification of the Airline. Values such as Gold or Platinum can be used.	< 32 AN	NO
additional_data.items[].passenger.phone
`ddi`	Passenger phone IDD.	< 3 N	NO
`ddd`	Passenger phone DDD.	< 3 N	NO
`number`	Passenger phone number.	< 9 N	NO
additional_data.extra_param.acquirer_params[]
`key`	Id of the additional information to be sent. For further details about this field, For more details about sending this field please contact Cielo.	< 1024 N	NO
`value`	Value of additional information to be sent.	< 1024 AN	NO
additional_data.shipment
`name`	Delivery recipient name.	< 255 AN	NO
`method`	Type of product delivery service. Allowed values: `SAME_DAY` – Delivery on the same day. `ONE_DAY` – Delivery overnight or on the next day. `TWO_DAY` – Delivery in two days. `THREE_DAY` – Delivery in three days. `LOW_COST` – Low cost delivery service. `PICKUP` – Product to be picked up in the store. `OTHER` – Other method. `NONE` – No delivery service, as it is a service or subscription.	< 9 AN	NO
additional_data.shipment.phones[]
`ddi`	Addressee phone IDD.	< 3 N	NO
`ddd`	Addressee phone DDD.	< 3 N	NO
`number`	Addressee phone number.	< 9 N	NO
additional_data.connections[]
`flight_date`	Date, hour and minute of flight departure in the `YYYY-MM-DDTHH:MM:SS` format. E.G.: 1991-01-02T08:30:00.	= 19 AN	NO
`from`	Airport code of the starting point of the trip. E.G.: CGH.	= 3 AN	NO
`to`	Airport code of the ending point of the trip. Ex.: GYN.	= 3 AN	NO

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

Payment Effectuation

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-dopayment}

Brazil

import ResponseCodes from './codigos-de-resposta.md';
import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';
import CardOnFile from './parametros-do-card-on-file.md';
import Recorrencia from './parametros-da-recorrencia.md';

After consuming the transaction creation service and obtaining a NIT, it's possible to proceed to the next step of the flow: calling the payment effectuation service. This operation must also be consumed on payment with schedule flows. In this case, Carat Portal assures that the schedule will only be activated if the payment is confirmed.

Call details

Resource: /v1/payments/{nit}
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 payment effectuation service call using the cURL tool.

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/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "13034649671",
    "customer_receipt": "====CUPOM COMPRADOR====",
    "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
    "authorizer_id": "2",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorizer_date": "13/07/2017T15:52",
    "authorization_number": "132030",
    "merchant_usn": "13034649671",
    "esitef_usn": "170713097340300",
    "sitef_usn": "132030",
    "host_usn": "999132030",
    "payment_date": "13/07/2017T15:52",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "000000000000005"
  }
}

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/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "PPC",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "13035748930",
    "customer_receipt": "==== CUPOM COMPRADOR ====",
    "merchant_receipt": "==== CUPOM ESTABELECIMENTO ====",
    "authorizer_id": "2",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorizer_date": "13/07/2017T15:58",
    "authorization_number": "132031",
    "merchant_usn": "13035748930",
    "esitef_usn": "170713097340340",
    "sitef_usn": "132031",
    "host_usn": "999132031   ",
    "payment_date": "13/07/2017T15:58",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "000000000000005"
  }
}

Payment with schedule

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/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "13040222890",
    "customer_receipt": "==== CUPOM COMPRADOR ====",
    "merchant_receipt": "==== CUPOM ESTABELECIMENTO ====",
    "authorizer_id": "2",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorizer_date": "13/07/2017T16:03",
    "authorization_number": "132032",
    "merchant_usn": "13040222890",
    "esitef_usn": "170713097340360",
    "sitef_usn": "132032",
    "host_usn": "999132032   ",
    "payment_date": "13/07/2017T16:03",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "000000000000005"
  },
  "schedule": {
    "status": "ATV",
    "sid": "qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
    "schedule_usn": "170713000000020",
    "amount": "900",
    "initial_date": "03/08/2017",
    "next_date": "03/08/2017",
    "number_of_times": "3",
    "installments": "1",
    "installment_type": "4",
    "soft_descriptor": "Subscription",
    "show_times_invoice": "false"
  }
}

Payment with stored card

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/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "token":"g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ=="
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "13034649671",
    "customer_receipt": "====CUPOM COMPRADOR====",
    "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
    "authorizer_id": "2",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorizer_date": "13/07/2017T15:52",
    "authorization_number": "132030",
    "merchant_usn": "13034649671",
    "esitef_usn": "170713097340300",
    "sitef_usn": "132030",
    "host_usn": "999132030",
    "payment_date": "13/07/2017T15:52",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "000000000000005"
  }
}

Payment with Via Certa Financiadora with financing plans

Attention:
It is important that in the creation of the transaction the installment is greater than 1 for installment.

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/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "security_code":"123",
      "number":"5555555555555555"
   },
   "authorizer_id": "313",
   "acquirer":{
      "financing_plan":"0302"
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "21105507366",
    "customer_receipt": "====CUPOM COMPRADOR====",
    "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
    "authorizer_id": "313",
    "acquirer_id": "1313",
    "acquirer_name": "Via Certa Financiadora",
    "authorizer_date": "21/11/2017T10:55",
    "authorization_number": "211982",
    "merchant_usn": "21105507366",
    "esitef_usn": "171121108905101",
    "sitef_usn": "211982",
    "host_usn": "999211982   ",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "0000000000000313",
    "payment_date": "21/11/2017T10:55"
  }
}

Payment with prefixes

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/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "security_code":"123",
      "number":"5555555555555555"
   },
   "acquirer":{
      "prefixes":{
         "TRAT":"1"
      }
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "21105507366",
    "customer_receipt": "====CUPOM COMPRADOR====",
    "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
    "authorizer_id": "2",
    "acquirer_id": "229",
    "acquirer_name": "Bin",
    "authorizer_date": "21/11/2017T10:55",
    "authorization_number": "211981",
    "merchant_usn": "21105507366",
    "esitef_usn": "171121108905100",
    "sitef_usn": "211981",
    "host_usn": "999211981   ",
    "amount": "1000",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "000000000000005",
    "payment_date": "21/11/2017T10:55"
  }
}

Payment Retry

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v1/payments/461e709fee10271129a52abd81b43ab08a777cf029a76c9bc56685d2a18eff40' \
--header 'Content-Type: application/json' \
--header 'merchant_id: LOJABIN' \
--header 'merchant_key: 03FB956839B2303A323D37B2968C76CD6A68EC6A377274F2' \
--data-raw '{
    "card": {
        "expiry_date": "1023",
        "number": "4220619003385567",
        "security_code": "123"
    }
}'
--verbose

Response:

{
    "code": "255",
    "message": "Transaction Denied",
    "payment": {
        "authorizer_code": "XYZ",
        "authorizer_message": "NEGADA",
        "status": "NEG",
        "nit": "461e709fee10271129a52abd81b43ab08a777cf029a76c9bc56685d2a18eff40",
        "order_id": "1648150290180",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "merchant_usn": "16114726760",
        "esitef_usn": "220411095715390",
        "sitef_usn": "500211",
        "host_usn": "004500211   ",
        "amount": "2000001",
        "payment_type": "C",
        "issuer": "1",
        "authorizer_merchant_id": "000000000000000",
        "terminal_id": "ES000001",
        "retryable_code": "01"
    }
}

Payment - Network Token

Some card brands have a tokenization solution that offers the storage of cards in safes at the brand itself, in an encrypted form. This brand tokenization is intended to improve the security and quality of the transmitted card information, which leads to possible increases in the conversion of approval by issuing banks.

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/payments/150533212ef1d2082ccff166fd2fb8d98ae645a541ad8ef54225c320bb0587a6' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "amount": 3000,
    "discount": 0,
    "installments": 1,
    "installment_type": 4,
    "authorizer_id": "2",
    "subtotal": 3000,
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555",
        "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
        "wallet_type": "network_token"
    }
}'
--verbose

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "7aef0962f2d2ec05c4cd35fd0d91a11fb4a5ce77e9dff69bbb5fc0992d0bc017",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "27/12/2022T17:06",
        "authorization_number": "276147",
        "esitef_usn": "221227000216620",
        "sitef_usn": "276147",
        "host_usn": "999276147   ",
        "amount": "3000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000023",
        "payment_date": "27/12/2022T17:06"
    }
}

Request parameters

The table below describes the request parameters of the payment effectuation service:

Parameter	Description	Format	Mandatory
`authorizer_id`	Code of the authorizer on Carat Portal. Learn more. If this field wasn't sent during the transaction creation phase, it will become mandatory when consuming the payment effectuation service.	< 3 N	COND.
`customer_postal_code`	User's postal code (CEP in Brazil). It must be sent for iCards via SiTef routed transactions, if the `is_customer_postal_code_required` field in card query service is marked as `true`.	< 8 N	COND.
`mcc`	The MCC (Merchant Category Code) is a code that classifies the business by the type of goods or services it provides.	< 4 N	NO
`subacquirer_merchant_id`	It is the merchant identification for the subacquirer.	< 22 N	NO
card	Card data.
`number`	Customer's card number (PAN). Brand generated token (DPAN) for network token payment. Learn more	< 19 N	YES
`cryptogram`	Cryptogram generated by the brand	= 28 A	Yes for network token payments
`expiry_date`	Card expiry date in `MMYY` format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory.	= 4 N	COND.
`security_code`	Card security code. This field may not be mandatory if the company has an agreement in the contract established with the acquirers, only for payments of certain areas. However, it is possible to configure the mandatory field in the merchant settings, consult Carat support for more information. Important: a payment with schedule implies on storing the customer's card data on Carat Portal's environment. However, for security reasons, the security code cannot be stored. Therefore, the scheduled payments will always be executed without the security code.	< 5 N	COND.
`holder`	Card holder name. Only mandatory for payments with e-Rede, GetNet WS and VR (SmartNet).	< 30 AN	COND.
`token`	HASH of a card stored on Carat Portal. It's not allowed to send an ‘open' card number (`number` field) and a stored card (`token` field) on the same request.	= 88 AN	NO
`wallet_transaction_id`	Digital wallet transaction ID. Currently, this functionality is only available to the Visa Checkout and VEE (via CardSE via SiTef) authorizer. It isn't allowed to send an ‘open' card number (`number` field), a stored card (`token` field) and a `wallet_transaction_id` on the same request.	< 25 AN	NO
`initial_wallet_transaction_id`	Informs if the wallet id (`wallet_transaction_id`) is being used for the first time. If so, send the value `true`, otherwise send `false`.	< 5 T/F	NO
`wallet_type`	Field that specifies whether the transaction is processed with PAN or DPAN. If “type” is empty, the default value is PAN (non-tokenized card number). If there is a tokenized transaction, you must send the value “network_token”.	AN	NO
external_authentication	This element receives MPI authentication result fields.
`version`	3DS version used in the authentication process (only version 2 is currently being accepted).	< 1 AN	NO
`eci`	Eletronic Commerce Indicator – Card holder authentication security level indicator.	< 3 N	NO
`reference_id`	Identifier of the cardholder's authentication transaction, performed in an external service to Carat (In our Web Checkout, the reference_id is referenced by ds.transId in the 3DS authentication response).	< 40 N	NO
`cavv`	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO
acquirer	Data required only to specific acquirers / routings.
`financing_plan`	Financing Plan code used for Via Certa Financiadora routed payments, only in case of installments plan with interest.	< 4 N	NO
`special_code`	Conductor/Renner SiTef routings general use code.	< 6 N	NO
`recurrency`	Flag that defines whether or not the payment is recurring. Accepted all routings via SiTef, Cielo e-Commerce, Global Payments WS, Stone WS, e.Rede REST and GetnetWS routings. In the case of a Stone WS recurrency, it is mandatory to send only one of the fields below, `is_first_recurring` OR `is_subsequent_recurring`.	< 5 T/F	NO
`recurrency_tid`	First transaction's TID. This field tells the first and the subsequent transactions apart. Use only if it is a recurrent payment.This field is used only for e.Rede REST routings using the brands Visa or Mastercard and for GetnetWS routing.	< 16 AN	NO
`is_first_recurring`	Flag used only for StoneWS routing. Indicates that the transaction is the first in a series of recurring transactions.	< 5 T/F	COND.
`is_subsequent_recurring`	Flag used only for StoneWS routing. It indicates that the transaction is the second or nth of a series of recurring transactions, where n > 2.	< 5 T/F	COND.
`recurrency_original_amount`	Original value of the transaction that started the recurrency. This value must be informed in all subsequent recurrences. Used only for recurrence. Field used only in BIN routing, mandatory when recurrence	< 18 AN	NO
`product_code`	Product code. It is mandatory in routing via Marisa.	< 6 N	COND.
`terminal`	Sitef terminal code. In absence Carat Portal will generate a random terminal code.	= 14 N	No
`company_code`	Sitef company code. In absence Carat Portal will use company code from merchant configuration.	= 8 N	No
`authorization_number`	Authorization number. Mandatory for Bradescard Voucher authorizer.	< 6 AN	COND.
acquirer.vouchers_filter[]	Choice of vouchers that will not be accepted. Options of "Vouchers": 01 - Food, 02 - Meal, 03 - Culture, 04 - Fuel, 05 - Benefit. Example: You do not want to accept Vouchers: Culture, Fuel, Benefit. You must send: "vouchers_filter": ["03", "04", "05"]
acquirer.prefixes	Element for sending SiTef prefixes, like CICLOS, CPLANO and VLRADD. If the prefix that was sent is not supported by card, Carat 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
acquirer.submerchant_split[]	It consists of an array for split payments, unique to BIN and Sipag routing, both via SiTef. It allows the division of parts of the total amount of the payment among other merchants. The maximum number of items allowed in this array is 5 items.
`submerchant_code`	BIN/Sipag merchant code	< 51 AN	NO
`submerchant_amount`	Transaction amount related to the merchant	< 12 N	NO
acquirer.card_on_file	It is intended for sending specific information such as card storage authorization, confirming that the cardholder has authorized the storage of the card. Learn more. Learn more.
`usage`	Identifies the usage. For instance, in case of storage authorization: `authorized`	< 11 AN	NO
`reason`	Itentifies the reason. For instance, in case of storage authorization: `card`	< 11 AN	NO

WARNING: The terminal e company_code parameters must be used only for SiTef routings and must be sent simultaneously.
It is also necessary send a request to the Carat Portal Support Team for the permission Allows sending Company and SiTef Terminal via REST.

Response parameters

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the payment effectuation 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
`authorizer_code`	Authorizer response code.	< 10 AN
`authorizer_message`	Authorizer response message.	< 500 AN
`status`	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
`nit`	Identifier of the payment transaction 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
`sitef_usn`	Unique sequential number of the payment transaction on SiTef.	= 6 N
`esitef_usn`	Unique sequential number of the payment transaction on Carat Portal.	= 15 N
`customer_receipt`	Customer's receipt.	< 4000 AN
`merchant_receipt`	Merchant's receipt.	< 4000 AN
`authorizer_id`	Code of the authorizer used on the transaction.	< 4 N
`acquirer_id`	Code of the acquirer used on the transaction.	< 4 N
`acquirer_name`	Name of the acquirer used on the transaction.	< 100 AN
`authorizer_date`	Payment authorization date returned by the authorizer in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`authorization_number`	Authorization number.	< 6 AN
`host_usn`	Host USN. Caveat for effecting PIX payments. Learn more.	< 15 AN
`tid`	ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef.	< 40 AN
`eci`	Eletronic Commerce Indicator (security level indicator of the payment transaction via Cielo e-Commerce).	<3 AN
`payment_date`	Payment authorization date on Carat Portal in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`issuer`	Issuer code returned by the authorizer.	< 5 AN
`authorizer_merchant_id`	Affiliation code of the merchant on the authorizer.	< 100 AN
`xid`	XID field returned on 3DS authentications or certain acquirers.	< 40 AN
`authentication_url`	Authentication URL returned on payment with authentication flows. Only available to Cielo e-Commerce.	< 56 AN
`balance`	Current balance after payments with Gift cards.	< 12 N
`recurrency_tid`	First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard.	< 16 AN
`retryable_code`	Reversibility indicator of a transaction whose authorization was denied by the authorizer. This field will be returned in the response to the card payment request and must be taken into account in the online store's transaction retry mechanism. Valid codes: `01` – Reversible Denied Transaction, Retain Later. `02` – Irreversible Denied Transaction, Non-Retentive.	= 2 N
payment.analysis
`code`	Response code of the fraud analysis operation.	< 4 N
`message`	Response message of the fraud analysis operation.	< 200 AN
`status`	Status of the fraud analysis transaction on Carat Portal. This field can assume the following value: `NOV` – New. `EXP` – Expired. `ACC` – Accepted `REJ` – Rejected `REV` – In review `INV` – Invalid	= 3 AN
schedule
`status`	Status of the schedule on Carat Portal. Learn more.	= 3 AN
`sid`	Schedule transaction identifier on Carat Portal.	= 64 AN
`schedule_usn`	Unique sequential number of the schedule on Carat Portal.	= 15 N
`authorizer_id`	Code of the authorizer to be used on the scheduled payments. In operations with tokenized card, if the authorizer is not informed, the authorizer code used in the card storage will be used.	= 4 N
`amount`	Amount of the scheduled payments specified by the merchant (in cents) on the creation of the transaction.	< 12 N
`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
`initial_date`	Execution date of the first scheduled payment in `DD/MM/YYYY` format.	= 10 D
`next_date`	Execution date of the next scheduled payment in `DD/MM/YYYY` format.	= 10 D
`number_of_times`	Total quantity of scheduled payments.	< 3 N
`installments`	Number of installments to be used on the scheduled payments.	< 2 N
`installment_type`	Financing type to be used on the scheduled payments.	< 2 N
`soft_descriptor`	Additional text that will be presented alongside the name of the establishment in the credit card invoice. This functionality is available to the acquirers Cielo e-Commerce, PayPal, e-Rede, ElavonWS and Stone.	< 30 AN
`show_times_invoice`	For finite time schedules, send this field with value `true` if you want to add at the end of the `soft_descriptor` field the current times/number of times (e.g. Subscription 3/12).	< 5 T/F
`terminal_id`	Terminal code used in the transaction	< 8 AN
`recurrency_tid`	First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard.	< 16 AN

Payment Effectuation with two Cards

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-domultiplepayment}

Brazil

import ResponseCodes from './codigos-de-resposta.md';

import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

After consuming the transaction creation service and obtaining a NIT, it's possible to proceed to the next step of the
flow: calling the payment effectuation service.

This can be done by either using a single payment method (read the
document "Payment effectuation service") or 2 (two) cards.

In this chapter we will write about paymets done by using 2 (two) payment methods, which we call Two cards payment.

Please contact our support team in order enable this operation in your store.

Flow

The two card payment flow has important differences when compared to the traditional payment.

The first difference is that there will be two transactions related to a single operation and each one of them is
used to effectuate the payment of one of the chosen payment methods. The first transaction is created in the Online
Payment transaction initialization call and the second is created indirectly during the two card payment
call.

The second difference is that some data of the first transaction is modified during the payment effectuation call.
Initially the first transaction has its own amount, installments and financing type. When the two card
call is done, this transaction amount is changed to the first payment method amount and the same will occur to the
installments and financing type if their value is informed in the request. The second transaction will also be created
with the amount, intallments and financing type informed by the second payment method in the request, but if the
intallments and financing type are not present, they will inherit the values passed in the original first
transaction. The sum of the first and second payment amounts must be equal to the amount in the Carat Portal
intialization transaction call.

The third difference is that two card payment response is composed by each transaction response. It
means that each of the transactions' responses can affect the results of the other one.

We will cover the Carat Portal predicted scenarios below.

Automatic confirmation flow

The automatic confirmation flow for two card payment has 3 (three) stages: transactions
update/initialization; payments effectuation; confirmations.

If any transaction fails, Carat Portal will not proceed to the next stage and will handle the failure as explained
in the cases presented below.

Sucessful payment

First payment fails

When the first payment fails, the second transaction will be promptly canceled and its payment call will not be
triggered to the acquirer. An issue will be registered and the merchant may contact Carat Portal's support team if
they find it necessary.

Response example

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "payments": [
    {
      "authorizer_code": "19",
      "authorizer_message": "19 Refaca Trans.",
      "status": "NEG",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25052428543",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:24",
      "authorization_number": "080384",
      "merchant_usn": "25052428543",
      "esitef_usn": "200325048537090",
      "sitef_usn": "606060",
      "host_usn": "707070",
      "amount": "1254784",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "00000005"
    },
    {
      "status": "CAN"
    }
  ]
}

Second payment fails

When the second payment fails, the first transaction will be undone. An issue will be registered and the merchant may
contact Carat Portal's support team if they find it necessary.

Response example

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "payments": [
    {
      "authorizer_code": "000",
      "authorizer_message": "Transacao Aprov.",
      "status": "PPN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25053142469",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:31",
      "authorization_number": "252490",
      "merchant_usn": "25053142469",
      "esitef_usn": "200325048537130",
      "sitef_usn": "252490",
      "host_usn": "999252490   ",
      "amount": "100",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "000000000000005",
      "payment_date": "25/03/2020T17:31"
    },
    {
      "authorizer_code": "255",
      "authorizer_message": "(2)Cartao invalido",
      "status": "NEG",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25053142469",
      "authorizer_id": "2",
      "acquirer_name": "REDE",
      "merchant_usn": "25053142469",
      "esitef_usn": "200325048537140"
    }
  ]
}

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "payments": [
    {
      "authorizer_code": "000",
      "authorizer_message": "Transacao Aprov.",
      "status": "PPN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25053142469",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:31",
      "authorization_number": "252490",
      "merchant_usn": "25053142469",
      "esitef_usn": "200325048537130",
      "sitef_usn": "252490",
      "host_usn": "999252490   ",
      "amount": "100",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "000000000000005",
      "payment_date": "25/03/2020T17:31"
    },
    {
      "authorizer_code": "255",
      "authorizer_message": "(2)Cartao invalido",
      "status": "NEG",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25053142469",
      "authorizer_id": "2",
      "acquirer_name": "Bin",
      "merchant_usn": "25053142469",
      "esitef_usn": "200325048537140"
    }
  ]
}

First confirmation fails

When the first confirmation fails, the second transaction will be undone. An issue will be registered and the merchant
may contact Carat Portal's support team if they find it necessary.

Response example

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "payments": [
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "PEN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20031345238",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "IPG",
      "authorizer_date": "25/03/2020T17:44",
      "authorization_number": "526985",
      "merchant_usn": "20031345238",
      "esitef_usn": "200325048537170",
      "host_usn": "350815827",
      "tid": "YES80192700",
      "amount": "103",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:44"
    },
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "PPN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20031345238",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "IPG",
      "authorizer_date": "25/03/2020T17:44",
      "authorization_number": "308718",
      "merchant_usn": "20031345238",
      "esitef_usn": "200325048537180",
      "host_usn": "916699212",
      "tid": "YES47652463",
      "amount": "102",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:44"
    }
  ]
}

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "payments": [
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "PEN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20031345238",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:44",
      "authorization_number": "526985",
      "merchant_usn": "20031345238",
      "esitef_usn": "200325048537170",
      "host_usn": "350815827",
      "tid": "YES80192700",
      "amount": "103",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:44"
    },
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "PPN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20031345238",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:44",
      "authorization_number": "308718",
      "merchant_usn": "20031345238",
      "esitef_usn": "200325048537180",
      "host_usn": "916699212",
      "tid": "YES47652463",
      "amount": "102",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:44"
    }
  ]
}

Second confirmation fails

When the second confirmation fails, the first transaction will be already confirmed. Therefore, it must be manually
cancelled if the merchant finds it necessary by using either the REST cancellation call or the Merchant Web Page. An
issue will be registered and the merchant may contact Carat Portal's support team if they find it necessary.

Response example

{
  "code": "255",
  "message": "Transaction Denied",
  "payments": [
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "CON",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20030404545",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "IPG",
      "authorizer_date": "25/03/2020T17:48",
      "authorization_number": "488040",
      "merchant_usn": "20030404545",
      "esitef_usn": "200325048537190",
      "host_usn": "572994560",
      "tid": "YES64194442",
      "amount": "102",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:48"
    },
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "PEN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20030404545",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "IPG",
      "authorizer_date": "25/03/2020T17:48",
      "authorization_number": "454463",
      "merchant_usn": "20030404545",
      "esitef_usn": "200325048537200",
      "host_usn": "108829897",
      "tid": "YES45823552",
      "amount": "103",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:48"
    }
  ]
}

{
  "code": "255",
  "message": "Transaction Denied",
  "payments": [
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "CON",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20030404545",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:48",
      "authorization_number": "488040",
      "merchant_usn": "20030404545",
      "esitef_usn": "200325048537190",
      "host_usn": "572994560",
      "tid": "YES64194442",
      "amount": "102",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:48"
    },
    {
      "authorizer_code": "200",
      "authorizer_message": "Function performed error-free [Cód.: 00]",
      "status": "PEN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20030404545",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "414",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:48",
      "authorization_number": "454463",
      "merchant_usn": "20030404545",
      "esitef_usn": "200325048537200",
      "host_usn": "108829897",
      "tid": "YES45823552",
      "amount": "103",
      "payment_type": "C",
      "payment_date": "25/03/2020T17:48"
    }
  ]
}

Payment with late confirmation flow

The payment with late confirmation flow has 2 (two) stages: transactions update/initialization; payments effectuation.

If any transaction fails, Carat Portal will not proceed to the next stage and will handle the failure as explained
in the cases presented below.

Succesful payment

First payment fails

When the first payment fails, the second transaction will be promptly canceled and its payment call will not be
triggered to the acquirer.

Response example

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "payments": [
    {
      "authorizer_code": "19",
      "authorizer_message": "19 Refaca Trans.",
      "status": "NEG",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25052428543",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:24",
      "authorization_number": "080384",
      "merchant_usn": "25052428543",
      "esitef_usn": "200325048537090",
      "sitef_usn": "606060",
      "host_usn": "707070",
      "amount": "1254784",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "00000005"
    },
    {
      "status": "CAN"
    }
  ]
}

Second payment fails

When the second payment fails, the first transaction will be undone.

Response example

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "payments": [
    {
      "authorizer_code": "000",
      "authorizer_message": "Transacao Aprov.",
      "status": "PPN",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25053142469",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "25/03/2020T17:31",
      "authorization_number": "252490",
      "merchant_usn": "25053142469",
      "esitef_usn": "200325048537130",
      "sitef_usn": "252490",
      "host_usn": "999252490   ",
      "amount": "100",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "000000000000005",
      "payment_date": "25/03/2020T17:31"
    },
    {
      "authorizer_code": "255",
      "authorizer_message": "(2)Cartao invalido",
      "status": "NEG",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "25053142469",
      "authorizer_id": "2",
      "acquirer_name": "REDE",
      "merchant_usn": "25053142469",
      "esitef_usn": "200325048537140"
    }
  ]
}

Call details

Resource: /v1/payments/multiple/{nit}
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 payment effectuation service call using the cURL tool.

Payment

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/payments/multiple/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "multiple_payment_methods": [
        {
            "number": "45518201234512345",
            "expiry_date": "1222",
            "security_code": "123",
            "authorizer_id": "218",
            "installments": "1",
            "installment_type": "4",
            "amount": "512"
        },
        {
            "number": "45518201234512345",
            "expiry_date": "1222",
            "security_code": "123",
            "authorizer_id": "218",
            "installments": "1",
            "installment_type": "4",
            "amount": "510"
        }
    ]
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payments": [
    {
      "authorizer_code": "000",
      "authorizer_message": "Transacao Aprov.",
      "status": "PPC",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20125445982",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "20/03/2020T14:32",
      "authorization_number": "202650",
      "merchant_usn": "16013439434",
      "esitef_usn": "200320048363850",
      "sitef_usn": "202650",
      "host_usn": "999202650   ",
      "amount": "512",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "000000000000005",
      "payment_date": "20/03/2020T14:32"
    },
    {
      "authorizer_code": "000",
      "authorizer_message": "Transacao Aprov.",
      "status": "PPC",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20125445982",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "20/03/2020T14:32",
      "authorization_number": "202651",
      "merchant_usn": "16013439434",
      "esitef_usn": "200320048363860",
      "sitef_usn": "202651",
      "host_usn": "999202651   ",
      "amount": "510",
      "payment_type": "C",
      "issuer": "2",
      "authorizer_merchant_id": "000000000000005",
      "payment_date": "20/03/2020T14:32"
    }
  ]
}

Payment with stored card

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/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "multiple_payment_methods": [
        {
            "token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
            "authorizer_id": "1",
            "installments": "1",
            "installment_type": "4",
            "amount": "512",
            "security_code": "123"
        },
        {
            "token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
            "authorizer_id": "2",
            "installments": "1",
            "installment_type": "3",
            "amount": "510",
            "security_code": "321"
        }
    ]
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payments": [
    {
      "authorizer_code": "000",
      "authorizer_message": "Transacao Aprov.",
      "status": "PPC",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20125445982",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "20/03/2020T14:32",
      "authorization_number": "202650",
      "merchant_usn": "16013439434",
      "esitef_usn": "200320048363850",
      "sitef_usn": "202650",
      "host_usn": "999202650   ",
      "amount": "512",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "000000000000005",
      "payment_date": "20/03/2020T14:32"
    },
    {
      "authorizer_code": "000",
      "authorizer_message": "Transacao Aprov.",
      "status": "PPC",
      "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id": "20125445982",
      "customer_receipt": "====CUPOM COMPRADOR====",
      "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
      "authorizer_id": "2",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "20/03/2020T14:32",
      "authorization_number": "202651",
      "merchant_usn": "16013439434",
      "esitef_usn": "200320048363860",
      "sitef_usn": "202651",
      "host_usn": "999202651   ",
      "amount": "510",
      "payment_type": "C",
      "issuer": "2",
      "authorizer_merchant_id": "000000000000005",
      "payment_date": "20/03/2020T14:32"
    }
  ]
}

Request parameters

The table below describes the request parameters of the payment with multiple payment methods effectuation service:

Parameter	Description	Format	Mandatory
multiple_payment_methods[] Array of payment methods. Exactly 2 (two) payment methods must be sent. Each payment method is composed by the fields described below.
`authorizer_id`	Code of the authorizer on Carat Portal. Learn more. If this field wasn't sent during the transaction creation phase, it will become mandatory when consuming the payment effectuation service.	< 3 N	YES
`installments`	Number of installments. If this field is not sent, the value informed in the Carat Portal initialization transaction request will be used.	< 2 N	NO
`installment_type`	Financing type. If this field is not sent, the value informed in the Carat Portal initialization transaction request will be used.	< 2 N	NO
`amount`	Amount of the purchase assigned to this payment method (in cents).	< 12 N	YES
`number`	Customer's card number (PAN).	< 19 N	YES
`expiry_date`	Card expiry date in `MMYY` format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory.	= 4 N	COND.
`token`	HASH of a card stored on Carat Portal. It's not allowed to send an ‘open' card number (`number` field) and a stored card (`token` field) on the same request.	= 88 AN	NO
`security_code`	Card security code. This field may not be mandatory if the company has an agreement in the contract established with the acquirers, only for payments of certain areas. However, it is possible to configure the mandatory field in the merchant settings, consult Carat support for more information. Important: a payment with schedule implies on storing the customer's card data on Carat Portal's environment. However, for security reasons, the security code cannot be stored. Therefore, the scheduled payments will always be executed without the security code.	< 5 N	COND.

Response parameters

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below
describes the response parameters of the payment effectuation service:

Parameter	Description	Format
`code`	Two card operation Carat Portal response code. Any code different from `0` means failure. Learn more.	< 4 N
`message`	Two card operation Carat Portal response message.	< 500 AN
payments[]	Two card operation payments responses array. Each item corresponds to the response for one of the chosen payment methods. Its fields are described below.
`code`	Carat Portal response code for this payment method. Any code different from `0` means failure. Learn more..	< 4 N
`message`	Carat Portal response message for this payment method.	< 500 AN
`authorizer_code`	Authorizer response code.	< 10 AN
`authorizer_message`	Authorizer response message.	< 500 AN
`status`	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
`nit`	Identifier of the payment transaction on Carat Portal.	= 64 AN
`order_id`	Order code sent by the merchant on the creation of the transaction.	< 20 AN
`merchant_usn`	Unique sequential number sent by the merchant on the creation of the transaction.	< 12 N
`amount`	Amount of the purchase assigned to this payment method (in cents).	< 12 N
`sitef_usn`	Unique sequential number of the payment transaction on SiTef.	= 6 N
`esitef_usn`	Unique sequential number of the payment transaction on Carat Portal.	= 15 N
`customer_receipt`	Customer's receipt.	< 4000 AN
`merchant_receipt`	Merchant's receipt.	< 4000 AN
`authorizer_id`	Code of the authorizer used on the transaction.	< 4 N
`acquirer_id`	Code of the acquirer used on the transaction.	< 4 N
`acquirer_name`	Name of the acquirer used on the transaction.	< 100 AN
`authorizer_date`	Payment authorization date returned by the authorizer in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`authorization_number`	Authorization number.	< 6 AN
`host_usn`	Host USN.	< 15 AN
`tid`	ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef.	< 40 AN
`eci`	Eletronic Commerce Indicator (security level indicator of the payment transaction via e-Commerce).	< 3 AN
`payment_date`	Payment authorization date on Carat Portal in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`issuer`	Issuer code returned by the authorizer.	< 5 AN
`authorizer_merchant_id`	Affiliation code of the merchant on the authorizer.	< 100 AN
`xid`	XID field returned on 3DS authentications or certain acquirers.	< 40 AN
`authentication_url`	Authentication URL returned on payment with authentication flows.	< 56 AN
`balance`	Current balance after payments with Gift cards.	< 12 N
payment.analysis
`code`	Response code of the fraud analysis operation.	< 4 N
`message`	Response message of the fraud analysis operation.	< 200 AN
`status`	Status of the fraud analysis transaction on Carat Portal. This field can assume the following value: `NOV` – New. `EXP` – Expired. `ACC` – Accepted `REJ` – Rejected `REV` – In review `INV` – Invalid	= 3 AN

Payment Confirmation

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-confirm}

Brazil

import ResponseCodes from './codigos-de-resposta.md';
import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

After creating and authorizing a payment pending confirmation, the merchant must call the confirmation service to confirm or undo the payment using the same NIT obtained on the first step of the flow.

Call details

Resource: /v1/payments/{nit}
HTTP Method: PUT
Request format: query string
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

Examples

Below is an example of the payment confirmation service call using the cURL tool.

Request:

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

curl 
--request PUT "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "CON"
  }
}

Request parameters

The table below describes the request parameters of the payment confirmation service:

Parameter	Description	Format	Mandatory
`confirm`	This field must be sent with the value `true` if you want to confirm the transaction, or `false`, if you want to undo it.	< 5 T/F	YES
`amount`	Amount to be captured. It must be less than or equal to the authorized amount. Partial confirmations are only supported by non-SiTef routings. If this field is not sent, the total transaction amount is used.	< 12 N	NO

Response parameters

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the payment confirmation 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
`host_usn`	Host USN.	< 15 AN
`payment_date`	Payment authorization date on Carat Portal in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D

Payment Confirmation with two Cards

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-domultipleconfirm}

Brazil

import ResponseCodes from './codigos-de-resposta.md';
import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

After creating and authorizing a two cards payment pending confirmation, the merchant must call the two cards payment confirmation service to confirm or undo the payment using the same NIT obtained on the first step of the flow.

Flow

The two cards payment confirmation flow has two differences when compared to the traditional confirmation.

The first difference is that there will be two transactions related to a single operation and each one of them is used to confirm the payment of one of the chosen payment methods.

The second difference is that two cards payment confirmation response is composed by each transaction response. It means that each of the transactions' responses can affect the results of the other one.

We will cover the Carat Portal predicted scenarios below.

Successful confirmation

First confirmation fails

When the first confirmation fails, the second transaction will be undone. An issue will be registered and the merchant may contact Carat Portal's support team if they find it necessary.

Response example

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "confirmations": [
    {
      "code": "259",
      "message": "Denied transaction",
      "payment": {
        "authorizer_code": "409",
        "authorizer_message": "Brand / card type is invalid or not supported [Cód.: 5996]",
        "status": "PPC",
        "acquirer_id": "414"
      }
    },
    {
      "code": "0",
      "message": "OK. Transaction successful.",
      "payment": {
        "authorizer_code": "200",
        "authorizer_message": "Function performed error-free [Cód.: 00]",
        "status": "PPN",
        "acquirer_id": "414"
      }
    }
  ]
}

Second confirmation fails

When the second confirmation fails, the first transaction will be already confirmed. Therefore, it must be manually cancelled if the merchant finds it necessary by using either the REST cancellation call or the Merchant Web Page. An issue will be registered and the merchant may contact Carat Portal's support team if they find it necessary.

Response example

{
  "code": "1013",
  "message": "Error processing multiple payment methods",
  "confirmations": [
    {
      "code": "0",
      "message": "OK. Transaction successful.",
      "payment": {
        "authorizer_code": "200",
        "authorizer_message": "Function performed error-free [Cód.: 00]",
        "status": "CON",
        "acquirer_id": "414"
      }
    },
    {
      "code": "259",
      "message": "Denied transaction",
      "payment": {
        "authorizer_code": "409",
        "authorizer_message": "Brand / card type is invalid or not supported [Cód.: 5996]",
        "status": "PPC",
        "acquirer_id": "414"
      }
    }
  ]
}

Call details

Resource: /v1/payments/multiple/{nit}
HTTP Method: PUT
Request format: query string
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

Examples

Below is an example of the two cards payment confirmation service call using the cURL tool.

Requisição:

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

curl 
--request PUT "https://{{url}}/e-sitef/api/v1/payments/multiple/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "confirmations": [
    {
      "code": "0",
      "message": "OK. Transaction successful.",
      "payment": {
        "authorizer_code": "130",
        "status": "CON",
        "acquirer_id": "5"
      }
    },
    {
      "code": "0",
      "message": "OK. Transaction successful.",
      "payment": {
        "authorizer_code": "130",
        "status": "CON",
        "acquirer_id": "5"
      }
    }
  ]
}

Request parameters

The table below describes the request parameters of the payment with two cards confirmation service:

Parameter	Description	Format	Mandatory
`confirm`	This field must be sent with the value `true` if you want to confirm the transaction, or `false`, if you want to undo it.	< 5 T/F	YES

Response parameters

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the payment confirmation service:

Parameter	Description	Format
`code`	Two cards payment operation Carat Portal response code. Any code different from `0` means failure. [Learn more.](codigos-da-api.md#response-codes	< 4 N
`message`	Two cards payment operation Carat Portal response message.	< 500 AN
confirmations[]
`code`	Carat Portal response code for this payment method. Any code different from `0` means failure. Learn more..	< 4 N
`message`	Carat Portal response message for this payment method.	< 500 AN
payment
`status`	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
`authorizer_code`	Authorizer response code. This field is not returned if this is not the first call to the operation.	< 10 AN
`authorizer_message`	Authorizer response message. This field is not returned if this is not the first call to the operation.	< 500 AN
`acquirer_id`	Code of the acquirer used on the transaction. This field is not returned if this is not the first call to the operation.	< 4 N

Payment Confirmation for External Origin

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento-rest-confirm-origem-externa}

Brazil

import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

Introduction

The external origin payment confirmation functionality allows that a payment transaction created outside of Carat Portal can be confirmed inside of Carat Portal.

Currently this functionality allows payment transaction confirmation done in SiTef.

This operation is divided in two steps:

The creation of a transaction of “Confirmation” type that represents the payment transaction externally created.
The confirmation of the payment of this transaction.

Case of success

The flow below shows the happy path where a transaction is started and then the confirmation is sent.

External origin payment confirmation transaction creation

Call details

Resource: /v1/transactions
HTTP Method: POST
Request format: JSON
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`merchant_id`	Carat Portal store's ID. Production and certification IDs are different.	≤ 15 A	YES
`merchant_key`	Store authentication key in Carat Portal. Production and certification keys are different.	< 80 A	YES
`Content-Type`	Fixed value "application/json"	= 15 A	YES

Example

Request

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

curl  --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions'
--header 'merchant_id: xxxxxxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
    "merchant_usn": "21042858195",
    "order_id": "1621949459257",
    "amount": "300",
    "transaction_type": "confirmation",
    "is_transaction_origin_external": "true"
}'
--verbose

Response

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "confirmation": {
    "status": "PPC",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "order_id": "1621949459257",
    "merchant_usn": "21042858195",
    "amount": "300"
  }
}

Request parameters

The table below shows fields for the creation of external origin payment confirmation transaction.

Parameter	Description	Format	Mandatory
`amount`	Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas	< 12N	YES
`merchant_usn`	Unique sequential id for each order created by the store. NSU will be used in all communication with the store to identify the order. As this is a store-side access key, although it is optional for Carat Portal, it is strongly recommended that the field be formatted and sent by the store application.	< 12 N	NO
`order_id`	Order code to be displayed to the buyer, defined by the merchant. It should be different at each request to facilitate traceability. If the store's integration with the acquirer/routing networks (Cielo, Redecard, etc) is via SiTef (TEF), the field orderId, which has a maximum length of 40 characters, will be shortened to 12 characters due to a SiTef restriction. This reduction will be performed by keeping the characters from left to right (eg if an order code entered is 12345678901234567890 in Carat Portal, in SiTef it will only be 123456789012).	< 40 AN	NO
`transaction_type`	Fixed value `confirmation`	= 15 A	YES
`is_transaction_origin_external`	Fixed value `true`	= 5 AN	YES

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

External origin payment confirmation transaction effectuation

Call details

Resource: /v1/payments/{nit}
HTTP Method: PUT
Request format: JSON and query string
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`merchant_id`	Carat Portal store's ID. Production and certification IDs are different.	≤ 15 A	YES
`merchant_key`	Store authentication key in Carat Portal. Production and certification keys are different.	< 80 A	YES
`Content-Type`	Fixed value "application/json"	= 15 A	YES

Example

Request

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

curl  --location --request PUT 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/bacd62eb62c27f4bf2eae9cef74c93a02e831985eccb6de371628fd272ee5474?confirm=true'
--header 'merchant_id: xxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
    "authorizer_id": "1",
    "installments": "1",
    "installment_type": "4",
    "confirmation_data": "123456789012",
    "acquirer": {
        "route_id": "5",
        "authorization_number": "212991",
        "identification_number": "11111111111",
        "order_id": "1621949459257",
        "authorizer_date": "21/05/2021",
        "host_usn": "000212991   ",
        "terminal": "HA000006",
        "company_code": "00000000"
    }
}'
--verbose

Response

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "authorizer_code": "130",
    "status": "CON",
    "acquirer_id": "5",
    "host_usn": "000212991   "
  }
}

Request parameters - query string

Parameter	Description	Format	Mandatory
`confirm`	This field must be sent with the value `true` if you want to confirm the payment, or `false` if you want to undo the payment.	< 5 T/F	YES

Request parameters - JSON

Parameter	Description	Format	Mandatory
`amount`	Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas. If not informed, the value informed in the transaction creation is used.	< 12N	NO
`authorizer_id`	Code of the authorizer on Carat Portal. It must be the same value sent on the pre autorization.	< 3 N	YES
`installments`	Number of installments. Send `1` for spot sales.	< 2 N	NO(*)
`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	NO(*)
`confirmation_data`	Payment information returned by SiTef after effectuating a payment. This parameter is fundamental for the success of the confirmation. It is used by SiTef to identify the payment.	< 128 AN	NO
acquirer
`routing_id`	Routing information used by the payment done outside of Carat Portal. This parameter is fundamental for the success of the confirmation. It is used to identify the routing inside of SiTef.	< 5 N	YES
`host_usn`	Host/authorizer USN of the transaction to be confirmed.	= 9 N	NO(*)
`authorization_number`	Authorization number of the transaction to be confirmed.	< 6 N	NO(*)
`authorizer_date`	Pre-authorization date returned by the authorizer in `DD/MM/YYYY` format.	= 10 D	NO(*)
`order_id`	Order code used in the pre-authorization initiated outside Carat Portal.	< 40 AN	NO(*)
`identification_number`	CPF or CNPJ used in the pre-authorization initiated outside Carat Portal.	< 20 AN	NO(*)
`terminal`	SiTef terminal code. In absence Carat Portal will generate a random terminal code.	= 8 AN	NO(*)
`company_code`	SiTef company code. In absence Carat Portal will use company code from merchant configuration.	= 8 N	NO(*)

Note: All fields marked with NO(*) are optional and, if informed, Carat Portal will not be able to consist any one of them because they are not sent to SiTef in the confirmation operation.

Response parameters

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the payment confirmation 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
`host_usn`	Host USN.	< 15 AN
`payment_date`	Payment authorization date on Carat Portal in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D

Payments - V2 Single Request

Perform Payment

_{Source: https://docs.apis-fiserv.com/latam/docs/pagamento}

Brazil

import CardOnFile from './parametros-do-card-on-file.md';
import Recorrencia from './parametros-da-recorrencia.md';

API interface that allows the online store to process sales requisitions.

Call details

Resource: /v2/payments
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

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: ************' \
--header 'merchant_key: ************' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "121314",
    "installments": "10",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "10000",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'
--verbose

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1657810477538",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "14/07/2022T11:54",
        "authorization_number": "145778",
        "merchant_usn": "12050620649",
        "esitef_usn": "220714103502410",
        "sitef_usn": "145778",
        "host_usn": "999145778   ",
        "amount": "10000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000032",
        "payment_date": "14/07/2022T11:54"
    }
}

Sitef Payment - Token

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "1657833175201",
    "installments": "10",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "10000",
    "card": {
        "token": "qJgaDApmM1APmglEpPUq7PomYpCXVqPWLW0MuEws1ZeOk95tDhqkKp-3n4KUNXAzsYxIazMSxNNSUXJ0zgwcuA=="
    },
    "acquirer": {},
    "additional_data": {}
}'
--verbose

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "APROVADA",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1657833175201",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "14/07/2022T18:12",
        "authorization_number": "500335",
        "merchant_usn": "12050620649",
        "esitef_usn": "220714103502980",
        "sitef_usn": "500335",
        "host_usn": "007500335   ",
        "amount": "10000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000000",
        "terminal_id": "ES000001",
        "payment_date": "14/07/2022T18:12",
        "recurrency_tid": "999988887777666"
    }
}

Sitef Payment - Konduto antifraud

For further information, please refer to our specific Konduto section.

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "merchant_usn": "2423423434",
    "order_id": "1657904793420",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "1300",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    },
    "additional_data": {
        "anti_fraud": "enabled_before_auth",
        "visitor_id": "XKhas09jcks",
        "items": [
            {
                "title": "title1",
                "quantity": "1",
                "unit_price": "1111",
                "description": "description1",
                "id": "id1",
                "discount_amount": "111",
                "sku": "sku1",
                "creation_date": "11/01/2011"
            }
        ],
        "payer": {
            "name": "Marcos",
            "surname": "da Silva",
            "email": "

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1657904793420",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "15/07/2022T14:06",
        "authorization_number": "155321",
        "merchant_usn": "2423423434",
        "esitef_usn": "220715103604930",
        "sitef_usn": "155321",
        "host_usn": "999155321   ",
        "amount": "1300",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000015",
        "payment_date": "15/07/2022T14:06",
        "analysis": {
            "status": "ACC",
            "code": "0",
            "message": "Recommendation: [APPROVE] Score: [0,00]"
        }
    }
}

Payment with later capture

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "1657810601498",
    "installments": "10",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "10000",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    },
    "additional_data": {
        "postpone_confirmation": "true"
    }
}'

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "PPC",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1657810601498",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "14/07/2022T11:56",
        "authorization_number": "145779",
        "merchant_usn": "12050620649",
        "esitef_usn": "220714103502420",
        "sitef_usn": "145779",
        "host_usn": "999145779   ",
        "amount": "10000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000032",
        "payment_date": "14/07/2022T11:56"
    }
}

Confirmation Request:

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

curl  --location --request PUT 'https://{{url}}/e-sitef/api/v2/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true' \
--header 'Content-Type: application/json' \
--header 'merchant_id: ********' \
--header 'merchant_key: ********'

Confirmation Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "130",
        "status": "CON",
        "acquirer_id": "5",
        "host_usn": "999145779   ",
        "payment_date": "14/07/2022T11:58"
    }
}

Payment without order_id

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "merchant_usn": "12050620649",
    "installments": "10",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "10000",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'

Response:

{
    "code": "187",
    "message": "Empty order_id value"
}

Account validation payment - Zero Auth Dollar

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "1661350282230",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "0",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "200",
        "authorizer_message": "Success. [Cód.: 00]",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1661350282230",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "202",
        "acquirer_name": "e.Rede REST",
        "authorizer_date": "24/08/2022T11:11",
        "authorization_number": "866551",
        "merchant_usn": "12050620649",
        "esitef_usn": "220824105973790",
        "host_usn": "513089380",
        "tid": "220824105973790",
        "amount": "0",
        "payment_type": "C",
        "payment_date": "24/08/2022T11:11"
    }
}

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "200",
        "authorizer_message": "Success. [Cód.: 00]",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1661350282230",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "202",
        "acquirer_name": "Bin",
        "authorizer_date": "24/08/2022T11:11",
        "authorization_number": "866551",
        "merchant_usn": "12050620649",
        "esitef_usn": "220824105973790",
        "host_usn": "513089380",
        "tid": "220824105973790",
        "amount": "0",
        "payment_type": "C",
        "payment_date": "24/08/2022T11:11",
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

Payment - 3DS

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "1660136901859",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "1",
    "amount": "9900",
    "card": {
        "expiry_date": "1023",
        "number": "5555555555555555",
        "security_code": "123",
        "holder": "Joao Silva"
    },
    "external_authentication": {
        "xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
        "eci": "05",
        "cavv": "jMoRyYgNSt0ZAREBBu8LHI+3oZo="
    }
}'

Response:

{
    
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "00",
        "authorizer_message": "TRANSACAO EXECUTADA COM SUCESSO",
        "status": "CON",
        "nit": "1dac764c4e38f6bea19a30656bc6ecb40b4cd58f139e56870a638a6bf0bfa2c0",
        "order_id": "1660136901859",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "1",
        "acquirer_id": "407",
        "acquirer_name": "GetNetWS",
        "authorizer_date": "03/10/2022T14:25",
        "authorization_number": "267692",
        "merchant_usn": "12050620649",
        "esitef_usn": "221003109032570",
        "host_usn": "072483954509",
        "tid": "-1",
        "amount": "9900",
        "payment_type": "C",
        "authorizer_merchant_id": "142365",
        "payment_date": "03/10/2022T14:25"
  }
}

{
    
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "00",
        "authorizer_message": "TRANSACAO EXECUTADA COM SUCESSO",
        "status": "CON",
        "nit": "1dac764c4e38f6bea19a30656bc6ecb40b4cd58f139e56870a638a6bf0bfa2c0",
        "order_id": "1660136901859",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "1",
        "acquirer_id": "407",
        "acquirer_name": "Bin",
        "authorizer_date": "03/10/2022T14:25",
        "authorization_number": "267692",
        "merchant_usn": "12050620649",
        "esitef_usn": "221003109032570",
        "host_usn": "072483954509",
        "tid": "-1",
        "amount": "9900",
        "payment_type": "C",
        "authorizer_merchant_id": "142365",
        "payment_date": "03/10/2022T14:25",
        "standin_details": "000001",
        "cvv_result_code": "M"
  }
}

Payment - Network Token

Parameter	Description	Format	Required
`card`
`number`	Token generated by the brand (DPAN)	≤ 19 N	Yes
`cryptogram`	Cryptogram generated by the brand	= 28 A	Yes for network token payments
`wallet_type`	Field that specifies whether the transaction is processed with PAN or DPAN. You must send the value “network_token” for tokenized transactions.	AN	Yes for network token payments

Request:

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

curl  --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "1665002632429",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "10000",
    "card": {
        "number": "5555555555555555",
        "expiry_date": "1223",
        "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
        "wallet_type": "network_token"
    }
}'

Response parameters

Parameter	Description	Format
`card`
`par`	EMVCo introduced PAR (Payment Account Reference) to provide an industry-aligned approach designed to help link all token-based transactions associated with a specific account.	< 32
`suffix`	Last four digits of the PAN, returned by Visa and Mastercard in transactions carried out with DPAN (Network Token).	= 4

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "TRANSACAO APROVADA",
        "status": "CON",
        "nit": "1854a5dac2033afc012c4ed807183bf77f6179a75c79ec81c770a0bde8aef583",
        "order_id": "0001709151774770",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin (Via Servicos TEF)",
        "authorizer_date": "28/02/2024T17:22",
        "authorization_number": "226596",
        "merchant_usn": "1709151775",
        "esitef_usn": "240228062687260",
        "sitef_usn": "816339",
        "host_usn": "43734572890",
        "amount": "100",
        "payment_type": "C",
        "terminal_id": "ES000001",
        "card_par": "hI3C1LmpTY46qNx4YlsyOvbRQBg3o",
        "payment_date": "28/02/2024T17:22",
        "recurrency_tid": "055950827503911",
        "standin_details": "000001",
        "cvv_result_code": "M"
    },
    "card": {
        "par": "hI3C1LmpTY46qNx4YlsyOvbRQBg3o",
        "suffix": "0042"
    }
}

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "41252cb6d538652cd8293541c8740cbe9bbd1dc380ecd65ab340d9dc0abf1d4a",
        "order_id": "1665002632429",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "05/10/2022T17:43",
        "authorization_number": "050246",
        "merchant_usn": "12050620649",
        "esitef_usn": "221005109152250",
        "sitef_usn": "050246",
        "host_usn": "999050246   ",
        "amount": "10000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000007",
        "terminal_id": "ES000001",
        "payment_date": "05/10/2022T17:43"
    }
}

Payment confirmation service

Call details

Resource: /v1/payments/{nit}
HTTP Method: PUT
Request format: query string
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

Examples

Below is an example of the payment confirmation service call using the cURL tool.

Full payment confirmation

Request:

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

curl 
--request PUT "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "CON"
  }
}

Payment confirmation with partial amount

Request:

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

curl 
--request PUT "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true&amount=1000"
--header "merchant_id:xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
   "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "status": "CON",
        "acquirer_id": "5"
    }
}

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. For transactions routed through the acquirer Bin, there's a 20 characters limit.	< 40 AN	YES
`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.	< 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	< 3025 AN	NO
card	Card data.
`number`	Customer's card number (PAN). Brand generated token (DPAN) for network token payment. Learn more	< 19 N	YES
`expiry_date`	Card expiry date in `MMYY` format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory.	= 4 N	COND.
`security_code`	Card security code. This field may not be mandatory if the company has an agreement in the contract established with the acquirers, only for payments of certain areas. However, it is possible to configure the mandatory field in the merchant settings, consult Carat support for more information. Important: a payment with schedule implies on storing the customer's card data on Carat Portal's environment. However, for security reasons, the security code cannot be stored. Therefore, the scheduled payments will always be executed without the security code.	< 5 N	COND.
`holder`	Card holder name. Only mandatory for payments with e-Rede, GetNet WS and VR (SmartNet).	< 30 AN	NO
`token`	HASH of a card stored on Carat Portal. It's not allowed to send an ‘open' card number (`number` field) and a stored card (`token` field) on the same request.	= 88 AN	NO
`cryptogram`	Field that specifies whether the transaction is processed with PAN or DPAN. If “type” is empty, the default value is PAN (non-tokenized card number). If there is a tokenized transaction, you must send the value “network_token”.	AN	NO
`wallet_type`	Field that specifies whether the transaction is processed with PAN or DPAN. If “type” is empty, the default value is PAN (non-tokenized card number). If there is a tokenized transaction, you must send the value “network_token”.	AN	NO
external_authentication	This element receives MPI authentication result fields.
`eci`	Eletronic Commerce Indicator – Card holder authentication security level indicator.	< 3 N	NO
`xid`	External card holder authentication transaction id.	< 40 N	NO
`cavv`	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO
iata	This element contains specific fields for IATA transactions.
`departure_tax`	Departure tax in cents.	< 12 N	YES only for installment_type = 6 or 7
`first_installment`	Amount of the first installment on IATA transactions in cents. This functionality is available only for E-Rede acquirer.	< 12 N	NO
acquirer	Data required only to specific acquirers / routings.
`financing_plan`	Financing Plan code used for Via Certa Financiadora routed payments, only in case of installments plan with interest.	< 4 N	NO
`special_code`	Conductor/Renner SiTef routings general use code.	< 6 N	NO
`mid`	Acquirer merchant code - For BIN routings, the MID to be used by the merchant is unique. This field must be used if it is necessary to select a MID other than the default one.	< 15 AN	COND
`recurrency`	Flag that defines whether or not the payment is recurring. Accepted all routings via SiTef, Cielo e-Commerce, Global Payments WS, Stone WS, e.Rede REST and GetnetWS routings. In the case of a Stone WS recurrency, it is mandatory to send only one of the fields below, `is_first_recurring` OR `is_subsequent_recurring`.	< 5 T/F	NO
`recurrency_tid`	First transaction's TID. This field tells the first and the subsequent transactions apart. Use only if it is a recurrent payment.This field is used only for e.Rede REST routings using the brands Visa or Mastercard and for GetnetWS routing.	< 16 AN	NO
`is_first_recurring`	Flag used only for StoneWS routing. Indicates that the transaction is the first in a series of recurring transactions.	< 5 T/F	COND.
`is_subsequent_recurring`	Flag used only for StoneWS routing. It indicates that the transaction is the second or nth of a series of recurring transactions, where n > 2.	< 5 T/F	COND.
`recurrency_original_amount`	Original value of the transaction that started the recurrency. This value must be informed in all subsequent recurrences. Used only for recurrence. Field used only in BIN routing, mandatory when recurrence	< 18 AN	NO
`product_code`	Product code. It is mandatory in routing via Marisa.	< 6 N	COND.
`terminal`	Sitef terminal code. In absence Carat Portal will generate a random terminal code.	= 14 N	No
`company_code`	Sitef company code. In absence Carat Portal will use company code from merchant configuration.	= 8 N	No
`authorization_number`	Authorization number. Mandatory for Bradescard Voucher authorizer.	< 6 AN	COND.
acquirer.vouchers_filter[]	Choice of vouchers that will not be accepted. Options of "Vouchers": 01 - Food, 02 - Meal, 03 - Culture, 04 - Fuel, 05 - Benefit. Example: You do not want to accept Vouchers: Culture, Fuel, Benefit. You must send: "vouchers_filter": ["03", "04", "05"]
acquirer.prefixes	Element for sending SiTef prefixes, like CICLOS, CPLANO and VLRADD. If the prefix that was sent is not supported by card, Carat 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
acquirer.submerchant_split[]	It consists of an array for split payments, unique to BIN and Sipag routing, both via SiTef. It allows the division of parts of the total amount of the payment among other merchants. The maximum number of items allowed in this array is 5 items.
`submerchant_code`	BIN/Sipag merchant code	< 51 AN	NO
`submerchant_amount`	Transaction amount related to the merchant	< 12 N	NO
acquirer.card_on_file	It is intended for sending specific information such as card storage authorization, confirming that the cardholder has authorized the storage of the card. Learn more.
`usage`	Identifies the usage. For instance, in case of storage authorization: `authorized`	< 11 AN	NO
`reason`	Itentifies the reason. For instance, in case of storage authorization: `card`	< 11 AN	NO
		WARNING: The `terminal` e `company_code` parameters must be used only for SiTef routings and must be sent simultaneously. It is also necessary send a request to the Carat Portal Support Team for the permission Allows sending Company and SiTef Terminal via REST.
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
`visitor_id`	Visitor identifier obtained using Konduto's JavaScript	< 40 AN	NO
`description`	Product description	< 100 AN	NO
`discount_amount`	Discount amount of the product in cents	< 10 N	NO
`discount_info`	Discount information.	< 500 AN	NO
`sku`	Item product code	< 100 AN	NO
`creation_date`	Indicates the date of publication of the product on the merchant's site (Format: `DD/MM/YYYY`)	= 10 AN	NO
additional_data.payer	Element for sending data related to the payer.
`name`	Customer name	< 100 AN	YES
`surname`	Customer surname	< 100 AN	YES
`email`	Customer e-mail	< 100 AN	YES
`born_date`	Customer birth date (format : `YYYY-MM-DDTHH:MM:SS`)	= 19 AN	NO
`identification_number`	Customer document number	< 100 AN	NO
`creation_date`	Account creation date on the site (format: `DD/MM/YYYY` )	= 10 AN	NO
`is_new_client`	Boolean that indicates if the customer is using a recently created account in this purchase	< 5 T/F	NO
`is_vip_client`	Boolean that indicates if the customer is VIP or a frequent buyer	< 5 T/F	NO
additional_data.merchant	Element for sending data related to the merchant.
`email`	Merchant's e-mail address.	< 1024 AN	NO
`additional_data` `.passengers[]`		Passengers information
`name`	Passenger first name	< 100 AN	YES
`last_name`	Passenger last name	< 100 AN	YES
`legal_document`	Passenger document	< 100 AN	YES
`legal_document_type`	Passenger document type (`5` = passport, any other number = id)	< 8 AN	YES
`birth_date`	Passenger birth date (format: `YYYY-MM-DDTHH:MM:SS`)	< 17 AN	NO
`nationality`	Passenger nationality, following ISO 3166-1 alfa-3	= 3 AN	NO
`is_frequent_traveler`	Frequent traveler boolean	< 5 T/F	NO
`is_with_special_needs`	Boolean which indicates if it's a passenger with special needs	< 5 T/F	NO
`frequent_flyer_card`	Loyalty program type	< 255 AN	NO
`customer_class`	Loyalty program category	< 255 AN	NO
`additional_data` `.hotel_reservations[]`		Hotel reservation information
`hotel`	Hotel name	< 100 AN	YES
`category`	Hotel category	< 100 AN	NO
`additional_data` `.hotel_reservations[]` `.address`		Hotel address information
`street_name`	Hotel street name	< 255 AN	NO
`street_number`	Hotel street number	< 255 AN	NO
`complement`	Hotel address complement	< 100 AN	NO
`city`	Hotel city	< 100 AN	NO
`state`	Hotel state	< 100 AN	NO
`zip_code`	Hotel zip code	< 100 AN	NO
`country`	Hotel country code, following ISO 3166-1 alfa-3	= 3 AN	NO
`additional_data` `.hotel_reservations[]` `.rooms[]`		Hotel rooms information
`number`	Room number	< 100 AN	NO
`code`	Room code	< 100 AN	NO
`type`	Room type	< 100 AN	NO
`check_in_date`	Check-in date and time (format: `YYYY-MM-DDTHH:MM:SS`)	< 17 AN	YES
`check_out_date`	Check-out date and time (format: `YYYY-MM-DDTHH:MM:SS`)	< 17 AN	NO
`number_of_guests`	Number of guests	< 9999 N	NO
`board_basis`	Feeding regime	< 100 AN	NO
`additional_data` `.hotel_reservations[]` `.rooms[]` `.guests[]`		Hotel room guests information
`name`	Guest name	< 100 AN	YES
`document`	Guest document	< 8 AN	NO
`document_type`	Guest document type: `cpf` `rg` `passport` `id` `other`	< 8 AN	NO
`birth_date`	Guest birth date (format: `YYYY-MM-DDTHH:MM:SS`)	< 17 AN	NO
`nationality`	Guest nationality, following ISO 3166-1 alfa-3	= 3 AN
`additional_data` `.events[]`		Event information
`name`	Event name	< 255 AN	YES
`date`	Event date and time (format `YYYY-MM-DDTHH:MM:SS`)	< 17 AN	YES
`type`	Event type: `show` `theater` `movies` `party` `festival` `course` `sports` `corporate`	< 9 AN	YES
`subtype`	Event type details	< 255 AN	NO
`additional_data` `.events[]` `.venue`		Event venue information
`name`	Venue name	< 255 AN	NO
`street_name`	Venue street name	< 255 AN	NO
`street_number`	Venue street number	< 255 AN	NO
`city`	Venue city	< 255 AN	NO
`state`	Venue state	< 255 AN	NO
`country`	Venue country code, following ISO 3166-1 alfa-3	= 3 AN	NO
`capacity`	Venue capacity	< 255 AN	NO
`additional_data` `.events[]` `.tickets[]`		Event tickets information
`id`	Unique ticket identifier	< 255 AN	NO
`category`	Ticket category: `student` `senior` `government` `social` `regular`	< 10 AN	YES
`section`	Ticket section	< 255 AN	NO
`premium`	Premium ticket indicator	< 5 T/F	NO
`additional_data` `.events[]` `.tickets[]` `.attendee`		Event attendee information
`name`	Attendee name	< 255 AN	NO
`document`	Attendee document	< 100 AN	YES
`document_type`	Attendee document type: `cpf` `cnpj` `rg` `passport` `other`	< 100 AN	NO
`birth_date`	Attendee birth date (format: `YYYY-MM-DDTHH:MM:SS`)	< 17 AN	NO
additional_data.shipment.receiver_address
`street_name`	Shipment address street name.	< 255 AN	NO
`street_number`	Shipment address street number.	< 15 AN	NO
`complement`	Shipment address complement.	< 50 AN	NO
`zip_code`	Shipment zip code. E.G.: 21241-140.	< 9 AN	NO
`city`	Shipment city.	< 50 AN	NO
`state`	Shipment state.	= 2 AN	NO
`country`	Shipment country, following ISO 3166-1. E.G.: BRA	= 3 AN	NO
additional_data.browser
`email`	Email registered in the customer's browser.	< 100 AN	NO
`host_name`	Host name where the customer was before entering the store's website.	< 60 AN	NO
additional_data.items[]
`title`	Product name.	< 255 AN	NO
`quantity`	Quantity of the product to be acquired.	< 15 N	NO
`id`	Product identifier.	< 255 AN	NO
`unit_price`	Unit price of the product.	< 15 N	NO
additional_data.items[].passenger
`email`	Passenger email.	< 255 AN	NO
`legal_document`	Id of the passenger to whom the ticket was issued.	< 32 AN	NO
`name`	Passenger name.	< 120 AN	NO
`customer_class`	Classification of the Airline. Values such as Gold or Platinum can be used.	< 32 AN	NO
additional_data.items[].passenger.phone
`ddi`	Passenger phone IDD.	< 3 N	NO
`ddd`	Passenger phone DDD.	< 3 N	NO
`number`	Passenger phone number.	< 9 N	NO
additional_data.extra_param.acquirer_params[]
`key`	Id of the additional information to be sent. For further details about this field, see https://developercielo.github.io/Webservice-3.0/english.html#merchant-defined-data.	< 1024 N	NO
`value`	Value of additional information to be sent.	< 1024 AN	NO
additional_data.shipment
`name`	Delivery recipient name.	< 255 AN	NO
`method`	Type of product delivery service. Allowed values: `SAME_DAY` – Delivery on the same day. `ONE_DAY` – Delivery overnight or on the next day. `TWO_DAY` – Delivery in two days. `THREE_DAY` – Delivery in three days. `LOW_COST` – Low cost delivery service. `PICKUP` – Product to be picked up in the store. `OTHER` – Other method. `NONE` – No delivery service, as it is a service or subscription.	< 9 AN	NO
additional_data.shipment.phones[]
`ddi`	Addressee phone IDD.	< 3 N	NO
`ddd`	Addressee phone DDD.	< 3 N	NO
`number`	Addressee phone number.	< 9 N	NO
`additional_data` `.connections[]`		Travel connections information
`journey_type`	`OUTWARD` - outward journey `RETURN` - return trip	< 7 AN	YES
`origin_city`	Origin city	< 100 AN	YES, if `transport_type`=`bus`
`destination_city`	Destination city	< 100 AN	YES, se `transport_type`=`bus`
`from`	IATA airport code of the origin airport	= 3 AN		YES, if `transport_type`=`flight`
`to`	IATA airport code of the destination airport	= 3 AN	YES, if `transport_type`=`flight`
`departure_date`	Departure date and time (format: `YYYY-MM-DDTHH:MM:SS`)	< 17 AN	YES
`class`	Seat class name (Ex: `economy`, `business` or `first`)	< 8 AN	NO
`class_code`	Seat class code	< 20 AN	NO
`company`	Airline name	< 20 AN	NO
`additional_data` `.billing_data` `.address`		Billing address information
`street_name`	Billing street name	< 255 AN	NO
`street_number`	Billing street number	< 255 AN	NO
`complement`	Billing address complement	< 100 AN	NO
`city`	Billing city	< 100 AN	NO
`state`	Billing state	< 100 AN	NO
`zip_code`	Billing zip code	< 100 AN	NO
`country`	Billing country code, following ISO 3166-1 alfa-3	= 3 AN	NO
`additional_data` `.travel`		Travel information
`transport_type`	Travel transport type (`flight` or `bus`)	< 6 AN	YES
`expiration_date`	Expiration date (format: `DD/MM/YYYY` )	= 10 AN	NO

The table below describes the additional parameters that must be sent on a payment with fraud analysis (for the time being only available for Cielo e-Commerce):

Parameter	Description	Format	Mandatory
additional_data
`anti_fraud_institution`	Institution that will carry out the fraud analysis to the merchant. It must be send with the value `AUTHORIZER`.	= 10 AN	YES para análise de fraude
`anti_fraud`	Enables the fraud analysis service. Allowed values: `enabled_before_auth` – fraud analysis will be done BEFORE the payment authorization. If the analysis is rejected, the payment won't be initiated. `enabled_after_auth` – fraud analysis will be done AFTER the payment authorization. If the analysis is rejected, the payment will be cancelled.	< 19 AN	YES para análise de fraude
`journey_type`	Type of the trip. Allowed values: `ROUND_TRIP` – round trip. `OUTWARD` – outward. `RETURN` – return.	< 10 AN	NO

Response parameters

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the payment effectuation 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
`authorizer_code`	Authorizer response code.	< 10 AN
`authorizer_message`	Authorizer response message.	< 500 AN
`status`	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
`nit`	Identifier of the payment transaction on Carat.	= 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
`sitef_usn`	Unique sequential number of the payment transaction on SiTef.	= 6 N
`esitef_usn`	Unique sequential number of the payment transaction on Carat Portal.	= 15 N
`customer_receipt`	Customer's receipt.	< 4000 AN
`merchant_receipt`	Merchant's receipt.	< 4000 AN
`authorizer_id`	Code of the authorizer used on the transaction.	< 4 N
`acquirer_id`	Code of the acquirer used on the transaction.	< 4 N
`acquirer_name`	Name of the acquirer used on the transaction.	< 100 AN
`authorizer_date`	Payment authorization date returned by the authorizer in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`authorization_number`	Authorization number.	< 6 AN
`host_usn`	Host USN.	< 15 AN
`tid`	ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef.	< 40 AN
`eci`	Eletronic Commerce Indicator.	< 3 AN
`payment_date`	Payment authorization date on Carat Portal in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`issuer`	Issuer code returned by the authorizer.	< 5 AN
`authorizer_merchant_id`	Affiliation code of the merchant on the authorizer.	< 100 AN
`xid`	XID field returned on 3DS authentications or certain acquirers.	< 40 AN
`cavv`	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO
`recurrency_tid`	First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard.	< 16 AN
`terminal_id`	Terminal code used in the transaction	< 8 AN
`payment_type`	Payment type from the selected authorizer: `B` = boleto, `C` = credit, `D` = debit, `P` = Private Label credit card, `T` = bank transfer, `G` = gift card, `O` = other payment methods, `W` = Boleto NR via Web Service	= 1 AN
`standin_details`	This field provides additional information to identify whether a transaction was performed by the Stand-in on behalf of the issuer. Learn more.	< 6 AN
`cvv_result_code`	CVV result code (present only in Mastercard and Visa transactions). Values: M = Valid (match) N = Invalid (not matching) P = Not processed (issuer temporarily unavailable) U = not verified S = CVV2 must be on card	= 1 N
payment.analysis
`status`	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
`code`	Carat Portal response code. Any code different from `0` means failure. Learn more.	< 4 N
`message`	Carat Portal response message.	< 500 AN

Dynamic MCC Fields

Can be used for both payment and REST pre-authorization transactions

Request Parameters

Additionally to the fields of the Payment, 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

curl 
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "merchant_usn": "19035815234",
  "order_id": "1616438400044",
  "installments": "1",
  "installment_type": "4",
  "authorizer_id": "2",
  "amount": "1300",
  "soft_descriptor": "L012121",
  "additional_data": {
    "mcc": "1111",
    "subacquirer_merchant": {
      "id": "12345",
      "address": "Avenida Paulista, 2000",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "zip_code": "01107001",
      "identification_number": "53455823000178",
      "payment_facilitator_id": "654321",
      "phone_number": "+55 11 99999-9999"
    }
  },
  "card": {
      "expiry_date": "1222",
      "security_code": "123",
      "number": "5555555555555555"
  }
}

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "1657810477538",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "5",
        "acquirer_name": "Bin",
        "authorizer_date": "14/07/2022T11:54",
        "authorization_number": "145778",
        "merchant_usn": "12050620649",
        "esitef_usn": "220714103502410",
        "sitef_usn": "145778",
        "host_usn": "999145778   ",
        "amount": "10000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000032",
        "payment_date": "14/07/2022T11:54",
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

Updated 6 days ago

Did this page help you?

Payments Documentation (LATAM)

Table of Contents

Payments

Overview

Communication

Flow

Payment with automatic confirmation

Payment with late confirmation

Payments - V1 Double Request

Quick Start

What you'll need

Creating the transaction

Paying

Checking the payment status

Transaction Creation

Call details

Examples

Creating a payment with automatic confirmation

Creating a payment with late confirmation

Creating a payment with schedule

Creating a schedule without payment

Creating a payment with Cielo e-Commerce fraud analysis

Creating a payment with risk analysis (using Konduto antifraud)

Request parameters

Dynamic MCC Fields

Request Parameters

Can be used for Payment and Pre-Authorization REST Transaction creation service

Example

Response parameters

Payment Effectuation

Call details

Examples

Payment with automatic confirmation

Payment with late confirmation

Payment with schedule

Payment with stored card

Payment with Via Certa Financiadora with financing plans

Payment with prefixes

Payment Retry

Payment - Network Token

Request parameters

Response parameters

Payment Effectuation with two Cards

Flow

Automatic confirmation flow

Sucessful payment

First payment fails

Response example

Second payment fails

Response example

First confirmation fails

Response example

Second confirmation fails

Response example

Payment with late confirmation flow

Succesful payment

First payment fails

Response example

Second payment fails

Response example

Call details

Examples

Payment

Payment with stored card

Request parameters

Response parameters

Payment Confirmation

Call details

Examples

Request parameters

Response parameters

Payment Confirmation with two Cards

Flow

Successful confirmation

First confirmation fails

Response example

Second confirmation fails

Response example

Call details

Examples