Refund
WARNING: This page is a document under construction, subject to change without notice, and still uncoupled from our full documentation. If you wish to access all our documentation, check here.
Refund operations 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. |
Examples#
Below are some examples of the refund service call using the cURL tool.
Refund#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
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:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
In the refund response, a nit is also returned. This nit is the refund transaction identifier on Carat. Therefore, it can be used on a Transaction status query API to query the refund data.
Refund - Network Token#
Some card brands have a tokenization solution that offers the storage of cards in safes at the brand itself, in an encrypted form. This brand tokenization is intended to improve the security and quality of the transmitted card information, which leads to possible increases in the conversion of approval by issuing banks.
| Parameter | Description | Format | Required |
|---|---|---|---|
card | |||
number | Token generated by the brand (DPAN) | ≤ 19 N | Yes |
cryptogram | Cryptogram generated by the brand | = 28 A | No |
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 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 |