Cancel service · e-SiTef

After obtaining a cancel NIT in the previous step, the merchant will be able to reverse the desired payment.

After a successful cancellation, the payment transaction will change its status to EST (reversed). Depending on the acquirer, it may be possible to do partial reversals, which means cancelling a smaller amount than what was paid. In this case, the payment transaction will keep the CON status.

Call details

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

Parameter	Description	Format	Mandatory
`merchant_id`	Merchant code on e-SiTef. The production and certification codes will be different.	< 15 AN	YES
`merchant_key`	Merchant authentication key on e-SiTef. 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 cancel service calls using the cURL tool.

Cancelling a payment via SiTef

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/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:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"09/11/2017T18:23",
      "authorization_number":"092423",
      "merchant_usn":"9062259711",
      "esitef_usn":"171109108051261",
      "sitef_usn":"092424",
      "host_usn":"999092424   ",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005",
      "esitef_date":"09/11/2017T18:23",
      "is_host_cancel":"false"
   }
}

Cancelling a payment via Cielo e-Commerce

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"0",
      "authorizer_message":"Operation Successful",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"10022938077",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"201",
      "acquirer_name":"Cielo e-Commerce",
      "merchant_usn":"10022938091",
      "esitef_usn":"171110108163221",
      "amount":"1000",
      "payment_type":"C",
      "authorizer_merchant_id":"zzzzzzzzzzzzzzzzzz",
      "esitef_date":"10/11/2017T14:29",
      "is_host_cancel":"false"
   }
}

Cancel via host

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "number":"455182001234512345"
   },
   "amount":"2000",
   "acquirer":{
      "host_usn":"123123123",
      "sitef_usn":"123123",
      "authorizer_date":"090917",
      "authorizer_id":"1",
      "tef_product_code":"0001",
      "tef_flow_code":"01",
      "authorization_number":"123456"
   }
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK!",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"1",
      "acquirer_id":"1125",
      "acquirer_name":"Cielo",
      "authorizer_date":"09/11/2017T18:42",
      "authorization_number":"092425",
      "esitef_usn":"171109108051271",
      "sitef_usn":"092425",
      "host_usn":"000092425   ",
      "amount":"2000",
      "payment_type":"C",
      "authorizer_merchant_id":"020001355570001",
      "esitef_date":"09/11/2017T18:42",
      "is_host_cancel":"true"
   }
}

Cancel external origin

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "number":"455182001234512345"
   },
   "amount":"2000",
   "acquirer":{
      "host_usn":"123123123",
      "sitef_usn":"123123",
      "authorizer_date":"090917",
      "authorizer_id":"2",
      "authorization_number":"123456"
   }
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK!",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"09/11/2017T18:42",
      "authorization_number":"092425",
      "esitef_usn":"171109108051271",
      "sitef_usn":"092425",
      "host_usn":"000092425   ",
      "amount":"2000",
      "payment_type":"C",
      "authorizer_merchant_id":"020001355570001",
      "esitef_date":"09/11/2017T18:42"
   }
}

Request parameters

The table below describes the request parameters of the cancel service:

Parameter	Description	Format	Mandatory
`amount`	Amount in cents to be cancelled. It’s important to note that not every acquirer supports cancellations with an amount smaller than the payment amount (partial reversal). If this field is not sent, e-SiTef will assume the total amount of the payment.	< 12 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
	card
`number`	Customer card number (PAN). Mandatory when cancelling payments via SiTef.	< 19 N	COND.
`expiry_date`	Card expiry date in `MMYY` format. Its requirement depends on the selected acquirer.	= 4 N	COND.
`security_code`	Security code. It’s mandatory depending on the contract signed with the acquirer.	< 5 N	COND.
`token`	HASH of a card stored on e-SiTef. 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
acquirer	The fields of this element should only be sent in cases of cancel via host, cancel external origin or cancel PayPal transactions.
`host_usn`	Host/authorizer USN of the transaction to be cancelled. Mandatory for cancel via host and cancel external source.	< 20 N	COND.
`sitef_usn`	SiTef USN of the transaction to be cancelled. Mandatory for cancel via host and cancel external source.	= 6 N	COND.
`authorizer_date`	Payment authorization date returned by the authorizer in `DD/MM/YYYY` format. Mandatory for cancel via host and cancel external source.	= 10 D	COND.
`authorizer_id`	Code of the authorizer on e-SiTef. It must be the same value sent on the payment. Mandatory for cancel via host and cancel external source.	< 3 N	COND.
`tef_product_code`	TEF product code obtained on the payment. This field can receive the following values: `0001` - Visa `0080` - Mastercard These values can be altered by Cielo without previous warning. Mandatory for cancel via host and cancel external source via Cielo routing.	< 4 N	COND.
`tef_flow_code`	TEF flow code obtained on the payment. Currently, this field can only receive the value `01` (credit flow). Mandatory for cancel via host and cancel external source via Cielo routing.	< 2 N	COND.
`authorization_number`	Authorization number of the transaction to be cancelled. Mandatory for cancel via host and cancel external source.	< 60 N	COND.
`product_code`	Product code. It is mandatory in routing via Marisa.	< 6 N	COND.
`refund_type`	Type of cancellation you want to make about payment. It is mandatory and only used for routing via Paypal. Allowed values: Full - Full payment chargeback is desired. Partial - Partial payment chargeback is desired	< 7 AN	COND.
`currency_code`	Currency code to be used in chargeback according to ISO 4217. For Real, the code used is BRL. It is mandatory and only used for routing via Paypal.	< 3 AN	COND.
`invoice_id`	Merchant's own chargeback order code for future reference or tracking. Used for Paypal routing only.	< 127 AN	NO
`note`	Personalized message for chargeback reminders. Used for Paypal routing only	< 256 AN	NO
`retry_until`	Data and timeout until a chargeback attempt is made. Format: AAAA-MM-DDTHH:MM:SS. Used for Paypal routing only.	< 20 AN	NO
`refund_source`	Merchant funds source that will be used to perform the chargeback. Used for Paypal routing only. Allowed values: any - The merchant has no preference. Any available source of funds will be used. default - The funds source set up in the merchant's account will be used. instant - Merchant's balance will be used as a source of funds. eCheck - The “eCheck” option will be used as a source of funds. If the retailer's balance can cover the chargeback, the balance sheet will be used.	< 7 AN	NO
`merchant_store_details`	Merchant's establishment information. Used for Paypal routing only.	< 50 AN	NO
`refund_advice`	Indicator for customer who has already received a chargeback of the given transaction. Used for Paypal routing only.	< 5 AN	NO
`refund_item_details`	Details of individual item handled on chargeback. Used for Paypal routing only.		NO
`msg_sub_id`	This ID will uniquely identify the message and can be used to request the latest results from a previous request without the need to create a new request. This can be done, for example, on calls that have been timeout canceled or errors during the process. Used for Paypal routing only.	< 38 AN	NO
`terminal_id`	Used if it is a Point of Sale. Used for Paypal routing only.	< 50 AN	NO
`store_id`	Used if it is a Point of Sale. Used for Paypal routing only.	< 50 AN	NO
`terminal`	Sitef terminal code. In absence e-SiTef will generate a random terminal code.	= 14 N	NO
`company_code`	Sitef company code. In absence e-SiTef will use company code from merchant configuration.	= 8 N	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_amout`	Transaction amount related to the merchant	< 12 N	NO

WARNING: The terminal e company_code parameters must be used only in Cancel external origin. In this case, they must be sent simultaneously.
It is also necessary send a request to the e-SiTef Support Team for the permission Permite envio de Empresa e Terminal Sitef via REST.

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 cancel service:

Parameter	Description	Format
`code`	e-SiTef response code. Any code different from `0`(zero) means failure. Learn more.	< 4 N
`message`	e-SiTef response message.	< 500 AN
	cancellation
`authorizer_code`	Authorizer response code.	< 10 AN
`authorizer_message`	Authorizer response message.	< 500 AN
`status`	Status of the payment transaction on e-SiTef. Learn more.	= 3 AN
`nit`	Identifier of the cancel transaction on e-SiTef.	= 64 AN
`order_id`	Order code of the transaction sent by the merchant.	< 40 AN
`merchant_usn`	Unique sequential number of the transaction sent by the merchant.	< 12 N
`amount`	Amount of the cancel transaction as specified by the merchant (in cents).	< 12 N
`sitef_usn`	Unique sequential number of the cancel transaction on SiTef.	= 6 N
`esitef_usn`	Unique sequential number of the cancel transaction on e-SiTef.	= 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`	Cancel 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.	< 20 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
`esitef_date`	Cancel authorization date on e-SiTef 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
`is_host_cancel`	This field will return the value `true` in case of cancel via host.	< 5 T/F