Cancellation with Idempotence
Refund operations with idempotence are requested using the following endpoint using the transaction ID (NIT) generated in the sale authorization. Refund requests will be considered successful once the request is approved by acquirer, and the status of the original sale transaction in Carat will automatically change to EST (Refunded)
Note: The Refund process requires authentication with signature. The store must have an RSA encryption public key registered in Carat and must assemble a JWT signature (JSON Web Tokens) to be sent in the authorization header. In this case, the refund transaction information will be returned directly in the service response. Learn more.#
However, if Merchant has enabled mutual authentication (mTLS) with Carat, a JWT signature is no longer a requirement.
Call details#
- Resource:
/v2/cancellations/{nit} - HTTP Method:
POST - 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 |
Authorization | Merchant's signature in the Bearer {signature} format. Example: Bearer JHVGytfdgauygdauiw78264284527852897hagdg. This parameter is mandatory, unless the Merchant has enabled mutual authentication (mTLS) along with Carat. | < 2000 AN | COND. |
idempotency_key | It's like a random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API. | < 80 N | YES |
Examples#
Below are some examples of the refund service call using the cURL tool.
Refund#
Request:
Response:
IMPORTANT: Some acquirers may require the submission of card data in the request. In these cases, the following example shows how this request should be sent.
Request:
Response:
A nit is also returned in the cancellation request response. This nit is the identifier of the cancellation transaction in Carat. Therefore, it should only be used in the Query API to query the cancellation data.
Cancellation - Using the same idempotency_key and same payload#
Request:
It may happen that there are additional fields in the second call, but all the fields from the first request will be returned.
Response:
Cancellation - Using the same idempotency_key and payload with different amount#
Request:
Response:
Request parameters#
The table below describes the request parameters of the refund service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
amount | Amount in cents to be refunded. It’s important to note that not every acquirer supports refunds with an amount smaller than the payment amount (partial refund). If this field is not sent, Carat Portal will assume the total amount of the payment. | < 12 N | NO |
| card | The obligation of this object depends solely and exclusively on the acquirer used in the transaction. | ||
number | Customer's card number (PAN). Brand generated token (DPAN) for network token payment. Learn more | < 19 N | YES |
cryptogram | Cryptogram generated by the card brand | = 28 AN | NO |
expiry_date | Card expiry date in MMYY format. | = 4 N | COND. |
security_code | Security code. | < 5 N | COND. |
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 refund creation 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 refund transaction on Carat. | = 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 refund transaction as specified by the merchant (in cents). | < 12 N |
sitef_usn | Unique sequential number of the refund transaction on SiTef. | = 6 N |
esitef_usn | Unique sequential number of the refund 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 | Refund 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 | Refund 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 refund via host. | < 5 T/F |
payment_type | Payment type from the selected authorizer: B = boleto, C = credit, D = debit, P = Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = Boleto NR via Web Service | = 1 AN |