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 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.

EnvironmentMerchant 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).

FieldDescriptionRequired
merchantCode
Merchant Code is a unique identifier generated by Hesabe for each activated merchantYes
token
Transaction Token of the original transactionYes
refundAmount
Amount to be refunded, in KWD (minimum 0.250)Yes
refundMethod
"1" for Full Refund / "2" for Partial RefundYes

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

https://merchantapisandbox.hesabe.com/api/v1/refund
RefundRequest.php
$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"
    }
}