Cancel service
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 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 |
Examples#
Below are some examples of cancel service calls using the cURL tool.
Cancelling a payment via SiTef#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Cancelling a payment via BIN#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Cancel via host#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Response codes
See reference on API codes - response codes
Cancel external origin#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
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, Carat Portal 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 Carat Portal. 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. | ||
routing_id | Routing information used by the payment done outside of e-SiTef. It is used to identify the routing inside of SiTef. This information only make sense in external origin transaction. | < 5 N | NO |
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 Carat Portal. 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 - Visa0080 - MastercardThese 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 Carat Portal will generate a random terminal code. | = 14 N | NO |
company_code | Sitef company code. In absence Carat Portal 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 |
ecomm_pos_ref | This field will send and identification that will appear in the PDV field of the SiTef Web report for e-commerce transactions. | < 8 AF | NO |
WARNING: The
terminalecompany_codeparameters 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 Carat Portal Support Team for the permission Allows the sending of Company and SiTef Terminal through 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 | Carat Portal response code. Any code different from 0(zero) means failure. Learn more. | < 4 N |
message | Carat Portal 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 Carat Portal. Learn more. | = 3 AN |
nit | Identifier of the cancel transaction on Carat Portal. | = 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 Carat Portal. | = 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 Carat Portal 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 |