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 Carat Portal, 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#

Carat Portal has two methods of merchant authentication on the REST cancel interface: authenticity POST or signature.

In the authenticity POST method, Carat Portal 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 Carat Portal 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:
ParameterDescriptionFormatMandatory
merchant_idMerchant code on Carat Portal. The production and certification codes will be different.< 15 ANYES
merchant_keyMerchant authentication key on Carat Portal. The production and certification keys will be different.< 80 ANYES
Content-TypeIt must be sent with the value application/json.= 15 ANYES
AuthorizationMerchant's signature in the Bearer {signature} format. Example: Bearer JHVGytfdgauygdauiw78264284527852897hagdg.< 2000 ANNO

Examples#

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

Cancel creation with authenticity POST#

Request:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

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

Carat Portal 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:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl -X POST \
https://dominiodaloja.com.br \
-H 'Content-Type: application/x-www-form-urlencoded' \
-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:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://{{url}}/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"
}
}

Response codes

See reference on API codes - response codes

Request parameters#

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

ParameterDescriptionFormatMandatory
esitef_usnUSN of the payment to be reversed. This information is returned by Carat Portal after the payment is approved.= 15 NYES
order_idOrder ID of the payment to be cancelled. This field must only be sent in case of cancel via host.< 40 ANNO
merchant_usnUSN generated by the merchant for the payment to be cancelled. This field must only be sent in case of cancel via host.< 12 NNO

Authenticity POST parameters#

The table below describes the parameters sent by Carat Portal on the authenticity POST:

ParameterDescriptionFormat
nitIdentifier of the cancel transaction to be used in the next step of the flow.= 64 AN
pedidoOrder ID of the payment to be cancelled.< 20 AN
nsuUSN generated by the merchant for the payment to be cancelled.< 12 N
codigoLojaMerchant code on Carat Portal.< 15 AN

Carat Portal 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:

ParameterDescriptionFormat
codeCarat Portal response code. Any code different from 0(zero) means failure. Learn more.< 4 N
messageCarat Portal response message.< 500 AN
cancellation These fields are only returned when using signature authentication.
nitIdentifier of the cancel transaction to be used in the next step of the flow.= 64 AN
order_idOrder ID of the payment to be cancelled.< 20 AN
merchant_usnUSN generated by the merchant for the payment to be cancelled.< 12 N