Refund Request
A refund is a transaction process where a merchant returns funds to a customer after a payment has been processed
API Reference
Refund request
To raise a refund after success transaction
Refund list
To view the complete list of refund request records
Refund details
To get complete refund details
Cancel refund
To cancel a refund request using the refund ID
Refund Implementation Steps
Refunds go through the Merchant API: log in to get an access token, then send the refund request with that token, your access code and an encrypted body.
Minimum refund amount: 0.250 KWD
The refund API refuses amounts below 0.250 KWD ("The refund amount must be at least 0.250"). Checkout accepts payments from 0.200 KWD, so a payment below 0.250 KWD can't be refunded through the API. Contact Hesabe support to refund one.
Log in to the Merchant API
Call Merchant login to get an access_token. It's valid for 15 minutes. A new login or a token refresh ends any earlier token, so reuse one token across your calls rather than logging in for each request.
| Environment | Merchant API base URL |
|---|---|
| Sandbox | https://merchantapisandbox.hesabe.com |
| Production | https://merchantapi.hesabe.com |
Create the refund payload
Build the JSON payload and encrypt it with your secret key and IV, the same way as for checkout (see the Encryption Library).
| Field | Description | Required |
|---|---|---|
merchantCode | Merchant Code is a unique identifier generated by Hesabe for each activated merchant | Yes |
token | Transaction Token of the original transaction | Yes |
refundAmount | Amount to be refunded, in KWD (minimum 0.250) | Yes |
refundMethod | "1" for Full Refund / "2" for Partial Refund | Yes |
Send the refund request
POST the encrypted payload as data to /api/v1/refund, with the bearer token and your access code in the headers.
Sandbox Refund Request API
Below Refund API strictly for sandbox testing only. Never use these sandbox URL's in production environment
$baseUrl = 'https://merchantapisandbox.hesabe.com/api/v1'; // sandbox
$accessToken = '...'; // response.token.access_token from /api/v1/login
$payload = json_encode([
'merchantCode' => '842217', // Sandbox Merchant Code
'token' => '521042117249344539468767555844', // Transaction Token Number
'refundAmount' => '1.000', // Refund Amount (minimum 0.250)
'refundMethod' => '2', // "1" for Full Refund, "2" for Partial Refund
]);
$encryptedData = HesabeCrypt::encrypt($payload, $encryptionKey, $ivKey);
$ch = curl_init("{$baseUrl}/refund");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['data' => $encryptedData]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken,
'accessCode: ' . $accessCode,
'Content-Type: application/json',
'Accept: application/json',
],
CURLOPT_RETURNTRANSFER => true,
]);
$refundResponse = curl_exec($ch);The full request and response for every refund call are in the reference: Refund request, Refund list, Refund details and Cancel refund.
Refund Response Details
Decrypt the response with the same keys. A decrypted refund response looks like this:
{
"status": true,
"message": "Your refund request is waiting for approval",
"data": {
"token": "521042117249344539468767555844",
"amount": "1.000",
"order_reference_number": "1724934434",
"transaction_status": "SUCCESSFUL",
"refund_status": "PENDING",
"payment_type": "KNET",
"service_type": "Payment Gateway",
"transaction_datetime": "2024-08-29 15:27:38",
"refund_requested_at": "2024-09-04 15:04:44"
}
}Hosted Checkout
Integrate Hesabe's payment gateway directly into your website with our embedded checkout solution. Provide customers with a smooth, secure payment experience while maintaining complete control over the user journey.
Dynamic Commission Fees
We have introduced a new enhancement to the Checkout API allowing sub-merchants to dynamically specify a commission amount at the time of checkout. This change provides greater flexibility and control over transaction-level commission settings.