Cancel

1) Cancel

Carat Portal provides services for payment cancellation (reversal). The page covers an overview and cancel query concept in the cancel flow.

Key points

• Cancel flow includes transaction reversal and status verification.
• Authentication is required for secure processing.

Cancel - V1 Double Request

2) Quick Start

This guide presents the end-to-end cancellation flow for V1, including create cancellation, execute cancellation, and query status.

What you'll need

• Active account in homologation/production environment.
• HTTP client tool (Postman, REST Client, cURL).

Main steps

• Creating a cancel transaction
• Cancelling the payment
• Checking the cancel status

Example

Request (create cancellation):

curl
--request POST "https://{{url}}/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "esitef_usn":"<payment_usn>"
}
--verbose

Response:

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

3) Create Cancellation

This service starts the cancellation flow and returns the cancellation nit, required in the next step.

Call details

• Resource: /v1/cancellations
• HTTP Method: POST
• Request format: JSON
• Response format: JSON

Key sections

• Authenticity POST x signature
• Examples
• Request parameters
• Authenticity POST parameters
• Response parameters

Example

Request:

curl
--request POST "https://{{url}}/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "esitef_usn":"171109108051160"
}
--verbose

Response:

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

4) Cancel Effectuation

After obtaining the cancellation nit, this service executes the payment reversal.

Call details

• Resource: /v1/cancellations/{nit}
• HTTP Method: PUT
• Request format: JSON
• Response format: JSON

Key sections

• Cancelling a payment via SiTef
• Cancelling a payment via BIN
• Cancel via host
• Cancel external origin
• Request parameters
• Response parameters

Example

Request:

curl
--request PUT "https://{{url}}/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "security_code":"123",
      "number":"5555555555555555",
      "expiry_date":"1222"
   },
   "amount":"1000"
}
--verbose

Response (excerpt):

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "amount":"1000",
      "acquirer_name":"Bin",
      "is_host_cancel":"false"
   }
}

5) Cancel Via Host

Page focused on required configuration to allow cancellation via host.

Required configurations on Carat Portal

• Host cancellation requires merchant-side setup aligned with Carat configuration.
• This topic complements the execution flow from V1 cancel effectuation.

6) Cancel External Origin

Allows cancellation for transactions not present in Carat Portal database, for specific supported scenarios.

Scope

• Designed for external-origin transactions.
• Mentioned restriction: currently focused on specific SiTef-originated flows.

Configuration hints in page

• terminal
• company_code

Cancel - V2 Single Request

7) Refund

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

Refund endpoint for V2 single request cancellation flow.

Call details

• Resource: /v2/cancellations/{nit}
• HTTP Method: POST
• Request format: JSON
• Response format: JSON

Key sections

• Call details
• Examples
• Refund
• Refund - Network Token
• Request parameters
• Response parameters

Example

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 'Authorization: Bearer {{assinatura}}'

Response (excerpt):

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "cancellation": {
        "status": "CON",
        "nit": "1c1caed9c650b298e52e8b1acd7d9eb6b6e85bf029dc285f682b86e6283479ac",
        "order_id": "1665693831749",
        "amount": "1300",
        "acquirer_name": "e.Rede REST",
        "is_host_cancel": "false"
    }
}

8) Asynchronous Refund

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

Introduces asynchronous refund processing model, where cancellation requests are queued and processed asynchronously.

Covered topics

• Necessary configurations in Carat
• Flow related to cancellation processes
• Status mapping between Omnipay API and return treatment

Notes

• Designed for higher-volume processing scenarios.
• Moves away from immediate synchronous cancellation behavior.