Refund request
After completing a successful transaction, you can initiate a refund request using the details provided below
AuthorizationBearer <token>
Pass access token obtained from login endpoint
In: header
Header Parameters
accessCodestring
Pass the merchant access code issued by Hesabe
Acceptstring
application/json
Content-Typestring
application/json
datastring
Convert payload JSON object to encrypted string and send it to the server
Types of refund methods
Refunds can be processed in two different ways depending on the amount to be returned to the customer:
| Types | Description | Value |
|---|---|---|
| Full | To process a complete refund of the transaction amount | "1" |
| Partial | To process a partial refund of the total transaction amount | "2" |
Sample Encryption and Decryption Process:
The following steps demonstrate how to integrate with this API using sandbox credentials.
Step 1: Create JSON Object
{
"merchantCode": "842217", // Pass the merchant code provided by Hesabe
"refundAmount": "10.000", // Refund amount should be in KWD
"refundMethod": "1", // "1" for Full Refund , "0" for partial
"token": "84221717575602869376365549977" // Invoice token number
}Payload details:
Contains the list of parameters and their corresponding values required to make the API request.
| Field Name | Description | Required |
|---|---|---|
merchantCode | Pass the merchant code provided by Hesabe | Yes |
refundAmount | Pass the refund amount and it should be in KWD | Yes |
refundMethod | Pass the refund method "1" or "2" | Yes |
token | Pass the transaction token number | Yes |
Step 2: Convert the JSON object into an encrypted string format and post to Hesabe
{
"data": "0e7898bd7464d0c402fe8a949d9cbf9ba5d8ada481ab9f66e4555139335643f4e1904f125c6dac14503369ecf3f06cde1212ac5fdaef94ab225673f757a5a84ee182f9443ce727161e9720f0cb138e5d51a6a728003af542dec35e6a9d8eedae76430e633696b35aca4267c9a2cbb0e3"
}Step 3: Receive encrypted response from Hesabe:
{
"response": "60a8f6241932227b840a9f5e36987f4d818fba84808037f6ad7f9e741d18e666137c10c959c559d96d709e21deea5b73a4a8c4328b5e1a62d7bb7701583ded75042c544b9affdfeedbac8ffc60c081fc05facee37119c2398ac5b297bccde855d7c339a4f400d81c17ca183aead2f896f3553edfbbad6b644b7291e77871c7c6e460f0f83e6a6e43b4c267ebcd05de7eabb163aa8e22931aec142ddd223596b7d99af05a1bc1fed9e11febc2b8b02dc38ea9fe065dffa3cfb2b98ca7eaf9b22799e3afaccf7189276d8cb0cd53f4147b04aa6f716d941ed87cf495f1b67f90dea2837cd62f3f9aab5af2cb3682c01afc91d0abae85faf5d4fb27fe0fc1ef886d27f2d4760c8a57d5d9143cd28cd34e1cf17f22cb714ec435b327680bcdd9dff0e0050aab3910a10314e7369a942bf59f2cae260704d97a9ef58dac5ef206559b7bc0be76db125bed8d409581beb487db26aa89eeec9e545400ae01d8f6d88a32113f866a99b3050568dfc2437252a42587bcdf30e5f8469c63111247f61e9a63968b6ab0fc1b7290dbca1934e25f330ce96d3fde594e0c8c1b4fe95b7564e516bde5bcdbe7d5501f123d529cc8706ed9853dc2c873d00e3f7d4a4fcde359175621c2ab8c5089bd422eec65a2677bee920e220a7fe1e1e55919c7fc424ab609433fcbf5e92e8bc768c7faf7eb6e67b13a59612f7996a9902a5a1860d0449a7d6a20c6d8020ac15a8132a21736beeb5f878f1dae9376f4270647857d1cb068b628678a2495671cf05c5f5265083b57123cbf35e8be47e3f285ccd2a2c14aafd761048d4f71e9bc0df3faf29c648a6b4981b1b6d2e60ada68d3514cadb3bdce5277df547c8b2de77d7ef512eeee56fd3a0bf1791ad8e1a5f49196cdd53718b474b6c38fd613b26ecbefb27194d21eb3f35b3282be70a15ede2501900f1d17d343f63e3cd95cfd868e5d8117ef05586e2487d4c5bf54e70abc696d1f10f4a1f4f8dd397fcbb41917105c0dd4b552a7e41b5c4ec57f1824721e361ea8f110277f824c49aa50695757cb5f58e971236d53dcb5f8fe8be09a29c71979d854d035d71e27f57cfffbe1506458722861594028aaaf8b261c6645833d52f117856e11ddc423e4c842e6f195b0435f95e7406c1825bf90c4becf94dd8762f962bfbd0709a868"
}Step 4: Decrypt the api response and view the JSON output
{
"status": true,
"message": "Refund request has been added",
"response": {
"id": 1467,
"merchant_id": 84,
"amount": "10.000",
"refund_at": null,
"document_number": "",
"token": "84221717575602869376365549977",
"transaction_date": "2025-09-11 06:11:32",
"order_reference_number": "122274462",
"recover_method": "",
"status": 0,
"refund_method": 2,
"remarks": "",
"approved_by": "",
"total_balance_amount": "15.000",
"total_refunded_amount": "10.000",
"total_transaction_amount": "15.000",
"created_at": "2025-10-12 09:36:35",
"updated_at": "2025-10-12 09:36:35",
"transaction": {
"id": 159841,
"amount": 15,
"admin_charge": 0,
"token": "84221717575602869376365549977",
"payment_id": 1,
"payment_name": "KNET",
"display_name": "KNET",
"track_id": "343757",
"transaction_id": "525420000128686",
"service_id": 3,
"auth": "B76201",
"status": 1,
"created_at": "2025-09-11 06:11:32"
}
}
}Response Body
application/json
application/json
application/json
application/json
application/json
const body = JSON.stringify({ "data": "0e7898bd7464d0c402fe8a949d9cbf9ba5d8ada481ab9f66e4555139335643f4e1904f125c6dac14503369ecf3f06cde1212ac5fdaef94ab225673f757a5a84ee182f9443ce727161e9720f0cb138e5d51a6a728003af542dec35e6a9d8eedae76430e633696b35aca4267c9a2cbb0e3"})fetch("https://merchantapisandbox.hesabe.com/api/v1/refund", { method: "POST", headers: { "Content-Type": "application/json", "accessCode": "c333729b-d060-4b74-a49d-7686a8353481", "Accept": "application/json" }, body}){
"status": true,
"message": "Refund request has been added",
"response": {
"id": 1467,
"merchant_id": 84,
"amount": "10.000",
"refund_at": null,
"document_number": "",
"token": "84221717575602869376365549977",
"transaction_date": "2025-09-11 06:11:32",
"order_reference_number": "122274462",
"recover_method": "",
"status": 0,
"refund_method": 2,
"remarks": "",
"approved_by": "",
"total_balance_amount": "15.000",
"total_refunded_amount": "10.000",
"total_transaction_amount": "15.000",
"created_at": "2025-10-12 09:36:35",
"updated_at": "2025-10-12 09:36:35",
"transaction": {
"id": 159841,
"amount": 15,
"admin_charge": 0,
"token": "84221717575602869376365549977",
"payment_id": 1,
"payment_name": "KNET",
"display_name": "KNET",
"track_id": "343757",
"transaction_id": "525420000128686",
"service_id": 3,
"auth": "B76201",
"status": 1,
"created_at": "2025-09-11 06:11:32"
}
}
}{
"status": false,
"message": "Request not found, Please verify the request data",
"response": null
}{
"message": "The selected token is invalid.",
"errors": {
"token": [
"The selected token is invalid."
]
}
}{
"message": "Internal server error occurred"
}{
"status": false,
"code": 506,
"message": "Invalid Request Data",
"response": null
}