Refund request

After completing a successful transaction, you can initiate a refund request using the details provided below

POST
/api/v1/refund

Base URL

Sandbox Base URL

Strictly for sandbox testing. Never use the sandbox URL in your production environment.
https://merchantapisandbox.hesabe.com

Authorization

bearerAuth
headerAuthorizationBearer <JWT>

Pass access token obtained from login endpoint

Header Parameters

accessCode*string

Pass the merchant access code issued by Hesabe

Accept*string

application/json

Content-Type*string

application/json

Request Body

application/json
  1. body
data*string

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:

TypesDescriptionValue
FullTo process a complete refund of the transaction amount"1"
PartialTo 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, "2" for Partial Refund  "token": "84221717575602869376365549977" // Invoice token number}

Payload details:

Contains the list of parameters and their corresponding values required to make the API request.

Field NameDescriptionRequired
merchantCodePass the merchant code provided by HesabeYes
refundAmountPass the refund amount and it should be in KWDYes
refundMethodPass the refund method "1" or "2"Yes
tokenPass the transaction token numberYes

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

Details fetched successfully. Decrypt the server response to view the final result

application/json
  1. response
status?boolean
message?string
response?
Example Request
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})
Example Response
{  "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"    }  }}