Cancel creation service

Consuming this service is mandatory to the cancel flow. As a result from this operation, the merchant will obtain a NIT, which will be necessary for the next step of the flow.

NIT has a time limit for its use. This deadline is configured on e-SiTef, and if it's exceeded, the cancel transaction will go from status NOV (new) to EXP (expired), which blocks future operations with this transaction, making it necessary to consume the cancel creation service again.

Authenticity POST x signature

e-SiTef has two methods of merchant authentication on the REST cancel interface: authenticity POST or signature.

In the authenticity POST method, e-SiTef will send the data of the newly created cancel transaction to the registered authenticity URL of the merchant.

In the signature method, the merchant must have a public RSA encryption key registered on e-SiTef and prepare a JWT signature (JSON Web Tokens) to be sent in the Authorization header. In this case, the cancel transaction information will be returned directly in the response. Learn more.

Call details

Resource: /v1/cancellations
HTTP Method: POST
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
`Authorization`	Merchant's signature in the `Bearer {signature}` format. Example: `Bearer JHVGytfdgauygdauiw78264284527852897hagdg`.	< 2000 AN	NO

Examples

Below are some examples of the cancel creation service call using the cURL tool.

Cancel creation with authenticity POST

Request:

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

E-SiTef will then answer through the merchant's URL using a HTTPS POST request (x-www-form-urlencoded) with the necessary information for further cancellation:

Authenticity POST:

curl -X POST \
  https://dominiodaloja.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Postman-Token: 8306e1f9-dc45-4cb9-926e-8aeef97229b1' \
  -H 'cache-control: no-cache' \
  -d 'nsu=9055020677&nit=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr&pedido=09055020677&codigoLoja=xxxxxxxxxxxxxxx'

Response:

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

Cancel creation with signature

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc"
--data-binary
{
   "esitef_usn":"123451234512345"
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "merchant_usn":"9062259711"
   }
}

Request parameters

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

Parameter	Description	Format	Mandatory
`esitef_usn`	USN of the payment to be reversed. This information is returned by e-SiTef after the payment is approved. This field mustn't be sent in case of cancel external origin	= 15 N	COND
`order_id`	Order ID of the payment to be cancelled. This field must only be sent in case of cancel via host or cancel external origin.	< 40 AN	NO
`merchant_usn`	USN generated by the merchant for the payment to be cancelled. This field must only be sent in case of cancel via host or cancel external origin.	< 12 N	NO
`is_transaction_origin_external`	Indicates if the transaction was originated outside e-SiTef. It is mandatory to send this field with a value of 'true' to cancel external origin.	< 5 AN	COND

Authenticity POST parameters

The table below describes the parameters sent by e-SiTef on the authenticity POST:

Parameter	Description	Format
`nit`	Identifier of the cancel transaction to be used in the next step of the flow.	= 64 AN
`pedido`	Order ID of the payment to be cancelled.	< 20 AN
`nsu`	USN generated by the merchant for the payment to be cancelled.	< 12 N
`codigoLoja`	Merchant code on e-SiTef.	< 15 AN

e-SiTef may also send new parameters without previous warning, which means that the merchant's application must be prepared to receive extra parameters and simply ignore them.

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 cancel creation 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`	These fields are only returned when using signature authentication.
`nit`	Identifier of the cancel transaction to be used in the next step of the flow.	= 64 AN
`order_id`	Order ID of the payment to be cancelled.	< 20 AN
`merchant_usn`	USN generated by the merchant for the payment to be cancelled.	< 12 N