Idempotence

Brazil

Payment

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
`idempotency_key`	Random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API.	`< 80 N`	YES

Examples

Payment using the same `idempotency_key` with different `order_id`

Request:

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

Response:

{
  "code": "1270",
  "message": "Idempotent transaction body does not match the original",
  "payment": {
    "status": "INV",
    "nit": "6ffad47ea1446d76160f1241f0fdca39342521df4f3f577920d9c855047fb9a2",
    "order_id": "1657833175201",
    "merchant_usn": "12050620649",
    "esitef_usn": "230912025329730",
    "amount": "10000"
  }
}

Performing pre-authorization if the idempotency key is the same as that of a payment transaction

Request:

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

Response:

{
  "code": "1272",
  "message": "Idempotent transaction is not of the same type",
  "payment": {
    "status": "INV",
    "nit": "d081e89daa1a0e446b92ead4ed2325f860d4e1280aa4b407f32957ce17f62ee3",
    "order_id": "1657833175201",
    "merchant_usn": "12050620649",
    "esitef_usn": "230912025329774",
    "amount": "2220"
  }
}

Request parameters

idempotency_key — required header, up to 80 characters.
merchant_usn, order_id, installments, installment_type, authorizer_id, amount, and card follow the standard payment payload shown in the examples.

Response parameters

code — 0 on success; 1270 when the body differs; 1272 when the transaction type differs.
payment.status — CON on success, INV on idempotent mismatch.
nit, order_id, merchant_usn, esitef_usn, and amount identify the transaction returned by Carat.

Pre-Authorization

Pre-authorization interface that allows the merchant to perform pre-authorization requests in a single call.

Call details

Resource: /v2/preauthorizations
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
`idempotency_key`	Random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API.	`< 80 N`	YES

Examples

Pre-Authorization using the same `idempotency_key` with different `order_id`

Request:

curl --request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/" \
--header "Content-Type: application/json" \
--header "merchant_id: xxxxxxxx" \
--header "merchant_key: xxxxxxxxxxx" \
--header "idempotency_key: ************" 
--data-binary
{
  "merchant_usn": "12050620649",
  "order_id": "3232333",
  "installments": "1",
  "installment_type": "4",
  "authorizer_id": "2",
  "amount": "2220",
  "card": {
    "expiry_date": "1223",
    "security_code": "123",
    "number": "5555555555555555"
  }
}

Response:

{
  "code": "1270",
  "message": "Idempotent transaction body does not match the original",
  "pre_authorization": {
    "status": "INV",
    "nit": "a9c6e0c275bf6eecb7deca20ab96dfd4733ae1a2f4eb6fd8139df1af876598da",
    "order_id": "32323333",
    "merchant_usn": "12050620649",
    "esitef_usn": "230913025438024",
    "amount": "2220"
  }
}

Request parameters

idempotency_key — required header, up to 80 characters.
The request body follows the standard pre-authorization payload shown in the example.

Response parameters

code — 0 on success; 1270 when the body differs.
pre_authorization.status — CON on success, INV on idempotent mismatch.
nit, order_id, merchant_usn, esitef_usn, and amount identify the pre-authorization returned by Carat.

Pre-Authorization Capture

The capture of the Pre-Authorization is intended to effect the Pre-Authorization, which may be in the total amount or lower than the total value of the Pre-Authorization. The flow should be: do the pre-authorization operation and, if approved, call the capture service to complete the flow.

Call details

Resource: /v1/preauthorizations/capture/{nit}
HTTP Method: POST
Request format: JSON
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`Content-Type`	It must be sent with the value `application/json`.	`= 15 AN`	YES
`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
`idempotency_key`	Random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API.	`< 80 N`	YES

Examples

Example if the request has the same idempotency key and same payload

Request:

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "idempotency_key: ************" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "merchant_usn": "12050620649",
    "order_id": "3232333",
    "installments": "1",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "2220",
    "card": {
        "expiry_date": "1223",
        "security_code": "123",
        "number": "5555555555555555"
    }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "card": {
    "suffix": "5555",
    "bin": "555555"
  },
  "capture": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao Aprov.",
    "status": "CON",
    "nit": "4dc696ea6cb5feee8e3d1311604fe5385186cb81520c2eb7b8028d8e993a9706",
    "order_id": "3232333",
    "customer_receipt":"=== COMPROVANTE ===",
    "merchant_receipt":"=== COMPROVANTE ===",
    "authorizer_id": "2",
    "acquirer_id": "1005",
    "acquirer_name": "Redecard",
    "authorizer_date": "13/09/2023T17:25",
    "authorization_number": "136451",
    "merchant_usn": "12050620649",
    "esitef_usn": "230913025456394",
    "sitef_usn": "136451",
    "host_usn": "999136451   ",
    "amount": "2220",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "000000000000005",
    "acquirer_cnpj": "67844256000156"
  }
}

Request parameters

idempotency_key — required header, up to 80 characters.
The request body follows the standard capture payload shown in the example.

Response parameters

code — 0 on success.
card.suffix and card.bin identify the captured card.
capture.status, capture.nit, capture.order_id, capture.amount, and authorizer/acquirer fields identify the capture result.

Refund

Note: The Refund process requires authentication with signature. The store must have an RSA encryption public key registered in Carat and must assemble a JWT signature (JSON Web Tokens) to be sent in the authorization header. In this case, the refund transaction information will be returned directly in the service response.

Refund operations with idempotence are requested using the following endpoint using the transaction ID (NIT) generated in the sale authorization. Refund requests will be considered successful once the request is approved by acquirer, and the status of the original sale transaction in Carat will automatically change to EST (Refunded).

Call details

Resource: /v2/cancellations/{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
`Authorization`	Merchant's signature in the `Bearer {signature}` format. Example: `Bearer {TOKEN_JWT_EXAMPLE}`. This parameter is mandatory, unless the Merchant has enabled mutual authentication (mTLS) along with Carat.	`< 2000 AN`	COND.
`idempotency_key`	Random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API.	`< 80 N`	YES

Examples

Refund

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/0a5e7dc9ef8ed24819c06a9bc1ed71f653671c931bd33fa49413477352de40d1' \
--header 'Content-Type: application/json' \
--header 'merchant_id: xxxxxxxxxxxxxxx' \
--header 'merchant_key: xxxxxxxxxxxxxxx' \
--header 'idempotency_key: ************' \
--header 'Authorization: Bearer {{assinatura}}'

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "cancellation": {
    "authorizer_code": "200",
    "authorizer_message": "Refund successful. [Cd.: 359]",
    "status": "CON",
    "nit": "1c1caed9c650b298e52e8b1acd7d9eb6b6e85bf029dc285f682b86e6283479ac",
    "order_id": "1665693831749",
    "customer_receipt":"=== COMPROVANTE ===",
    "merchant_receipt":"=== COMPROVANTE ===",
    "authorizer_id": "2",
    "acquirer_id": "202",
    "acquirer_name": "e.Rede REST",
    "authorizer_date": "08/09/2022T17:43",
    "merchant_usn": "12050620649",
    "esitef_usn": "221013109643171",
    "host_usn": "828420940",
    "tid": "221013109643160",
    "amount": "1300",
    "payment_type": "C",
    "esitef_date": "08/09/2022T17:43",
    "is_host_cancel": "false"
  }
}

Cancellation - Using the same `idempotency_key` and same payload

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/1bfff28297349381d8fc66fd0162c711ea5a61d932077d0109fe5642e7188e74' \
--header 'Content-Type: application/json' \
--header 'merchant_id: xxxxxxxxxxxxxxx' \
--header 'merchant_key: xxxxxxxxxxxxxxx' \
--header 'idempotency_key: ************' \
--header 'Authorization: Bearer {{assinatura}}' \
--data-raw '{
    "amount": "1100",
    "card": {
        "expiry_date": "1223",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "cancellation": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao Aprov.",
    "status": "CON",
    "nit": "70d70a62062d01deaf49a96c98e2c4f7306975c93164c01b5fa639fe8cb9ba05",
    "order_id": "1679514603756",
    "customer_receipt": ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....                                          \nSI                              Rede 5                                          \nMU               Codigo transacao: 400                                          \nLA             Codigo operacao: 200030                                          \nDO                       Valor: 111,00                                          \n.....S...I...M...U...L...A...D...O....                                          \nSI                   NSU SiTef: 136447                                          \nMU                      13/09/23 16:16                                          \nLA                    ID PDV: ES000053                                          \nDO             Estab.: 000000000000005                                          \n.....S...I...M...U...L...A...D...O....                                          \nSI                     Host: 999136447                                          \nMU         Transacao Simulada Aprovada                                          \nLA                                                                              \n                               (SiTef)                                          \n",
    "merchant_receipt": ".....S.O.F.T.W.A.R.E.E.X.P.R.E.S.S....                                          \nSI                              Rede 5                                          \nMU               Codigo transacao: 400                                          \nLA             Codigo operacao: 200030                                          \nDO                       Valor: 111,00                                          \n.....S...I...M...U...L...A...D...O....                                          \nSI                   NSU SiTef: 136447                                          \nMU                      13/09/23 16:16                                          \nLA                    ID PDV: ES000053                                          \nDO             Estab.: 000000000000005                                          \n.....S...I...M...U...L...A...D...O....                                          \nSI                     Host: 999136447                                          \nMU         Transacao Simulada Aprovada                                          \n                               (SiTef)                                          \n",
    "authorizer_id": "2",
    "acquirer_id": "1005",
    "acquirer_name": "Redecard",
    "authorizer_date": "13/09/2023T16:16",
    "authorization_number": "136446",
    "merchant_usn": "12050620649",
    "esitef_usn": "230913025455891",
    "sitef_usn": "136447",
    "host_usn": "999136447   ",
    "amount": "1100",
    "payment_type": "C",
    "issuer": "2",
    "authorizer_merchant_id": "000000000000005",
    "acquirer_cnpj": "67844256000156",
    "esitef_date": "13/09/2023T16:16",
    "is_host_cancel": "false"
  }
}

Cancellation - Using the same `idempotency_key` and payload with different amount

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/1bfff28297349381d8fc66fd0162c711ea5a61d932077d0109fe5642e7188e74' \
--header 'Content-Type: application/json' \
--header 'merchant_id: xxxxxxxxxxxxxxx' \
--header 'merchant_key: xxxxxxxxxxxxxxx' \
--header 'idempotency_key: ************' \
--header 'Authorization: Bearer {{assinatura}}' \
--data-raw '{
    "amount": "11100",
    "card": {
        "expiry_date": "1223",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'

Response:

{
  "code": "1270",
  "message": "Idempotent transaction body does not match the original",
  "cancellation": {
    "status": "INV"
  }
}

Request parameters

amount — amount in cents to be refunded.
card.number — customer PAN, brand token (DPAN), or network token payment card number.
card.cryptogram — cryptogram generated by the card brand.
card.expiry_date — card expiry date in MMYY format.
card.security_code — security code.

Response parameters

code — 0 on success; 1270 when the idempotent body differs.
cancellation.status — CON on success, INV on idempotent mismatch.
nit, order_id, merchant_usn, esitef_usn, host_usn, and amount identify the refund transaction returned by Carat.
is_host_cancel indicates whether the refund was performed via host.

Updated 5 days ago

Did this page help you?

Idempotence

Payment

Call details

Examples

Payment using the same idempotency_key with different order_id

Performing pre-authorization if the idempotency key is the same as that of a payment transaction

Request parameters

Response parameters

Pre-Authorization

Call details

Examples

Pre-Authorization using the same idempotency_key with different order_id

Request parameters

Response parameters

Pre-Authorization Capture

Call details

Examples

Example if the request has the same idempotency key and same payload

Request parameters

Response parameters

Refund

Call details

Examples

Refund

Cancellation - Using the same idempotency_key and same payload

Cancellation - Using the same idempotency_key and payload with different amount

Request parameters

Response parameters

Payment using the same `idempotency_key` with different `order_id`

Pre-Authorization using the same `idempotency_key` with different `order_id`

Cancellation - Using the same `idempotency_key` and same payload

Cancellation - Using the same `idempotency_key` and payload with different amount