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.

Important Notes

This feature is available only to sub-merchants where:

The sub-merchant has Dynamic Commission enabled
The parent/main merchant has also enabled Dynamic Commission

If you don't see this option, contact your parent merchant or Hesabe support to enable it.

Implementation Guide

Payment Checkout Integration Steps

Refer Hesabe Checkout API Guides before integrating subscription steps

Pre-requisites Setup

You can follow the Checkout Setup guide to get started.

Hesabe Request Handler

You can follow the Hesabe Request Handler guide to get started.

Dynamic Commission Checkout Flow Logic

How Hesabe Processes Dynamic Commission Requests:

checkout.php

  $baseUrl =  "http://sandbox.hesebe.com/api/";
  $CheckoutApiUrl = "{$baseUrl}/checkout"; 
  $requestData = [
      "merchantCode" => "842217",  // Sandbox
      "amount" => "100.000", 
      "paymentType" => "2", // Refer "List of Payment Types” Section
      "commission" => '0.500', // Total commission amount
      "responseUrl" => "https://sandbox.hesabe.com/customer-response?id=842217", 
      "failureUrl" => "https://sandbox.hesabe.com/customer-response?id=842217", 
      "version" => "2.0", 
      "orderReferenceNumber" => "9874659805", 
      "currency" => "KWD", 
      "name" => "customername", 
      "email" => "customeremail@gmail.com", 
      "mobile_number" => "66666666", 
      "variable1" => "First__variable", 
      "variable2" => "Second__variable", 
      "variable3" => "Third__variable", 
      "variable4" => "forth__variable", 
      "variable5" => "example.com",
      "webhookUrl" => 'https://yourdomain.com/example' 
  ];

Step	Condition	Action	Result
1	Commission parameter NOT provided	Skip dynamic commission feature	✅ Proceed with standard checkout flow
2	Commission parameter PROVIDED	Check: Is merchant a sub-merchant?	• YES → Continue to Step 3 • NO → ❌ Reject (feature unavailable)
3	Sub-merchant confirmed	Check: Does merchant have DC enabled?	• YES → Continue to Step 4 • NO → ❌ Reject (DC not enabled)
4	Sub-merchant DC enabled	Check: Does parent merchant have DC enabled?	• YES → Continue to Step 5 • NO → ❌ Reject (parent DC not enabled)
5	Both have DC enabled	Validate commission amount against rules	• Passes → Continue to Step 6 • Fails → ❌ Return Error 525
6	Validation passed	Process payment with your commission	✅ Checkout proceeds successfully
7	Validation failed	Return error response	❌ Error Code: 525 Message: "Invalid commission. Must be greater than minimum and less than transaction"

Quick Decision Tree:

Scenario	Flow	Outcome
No commission provided	Skip DC → Use standard checkout	✅ Normal payment flow
Commission provided + Sub-merchant + Both DC enabled + Commission valid	Process with dynamic rate	✅ Payment accepted with your rate
Commission provided + Not a sub-merchant	Skip DC	❌ Feature unavailable
Commission provided + Sub-merchant DC disabled	Skip DC	❌ Feature disabled on account
Commission provided + Parent merchant DC disabled	Skip DC	❌ Parent hasn't enabled DC
Commission provided + Commission invalid (below minimum or above amount)	Reject	❌ Error 525: Invalid commission

Validation Rules

The provided dynamic commission will be validated against the following criteria:

Rules	Description
Minimum Threshold	The commission must be greater than or equal to Hesabe platform main merchant commission
Hesabe Indirect Payment Method	If payment method is indirect, sub-merchant commission must be greater than maximum commission set for main merchant across all available payment methods
Hesabe Direct Payment Method	If payment method is direct, it is validated commission only against the specific payment type selected

Dynamic Commission Examples

Use Case: Dynamic Commission on a 100 KD Transaction

Aspect	✅ Equals Minimum	✅ Exceeds Minimum	❌ Below Minimum
Scenario	Commission equals Hesabe's minimum	Commission exceeds minimum	Commission below minimum
Transaction Amount	100.000 KD	100.000 KD	100.000 KD
Hesabe Platform Commission	0.200 KD	0.200 KD	0.200 KD (Required)
Your Commission	0.200 KD	0.500 KD	0.100 KD
Commission Status	✅ Equal to minimum	✅ Exceeds minimum	❌ Below minimum
Result	✅ APPROVED	✅ APPROVED	❌ REJECTED
Distribution	0.200 KD → Hesabe 0.000 KD → Parent Merchant	0.200 KD → Hesabe 0.300 KD → Parent Merchant	N/A - Payment Failed
Client Earns	0.000 KD	0.300 KD	0.000 KD (Rejected)
Error Code	-	-	525
Error Message	-	-	Invalid commission. Must be >= 0.200 KD
Next Steps	✅ Payment accepted	✅ Payment accepted	1. Increase to ≥ 0.200 KD 2. Use default commission 3. Review strategy
Summary	Payment accepted. Commission covers Hesabe fee exactly.	Payment accepted. Excess (0.300 KD) shared with parent merchant.	Payment rejected. Retry with valid commission.

Create checkout request

Pass the following parameters below:

Sandbox Checkout API

Below Checkout API strictly for sandbox testing only. Never use these sandbox URL's in production environment

https://sandbox.hesabe.com/api/checkout

Production Checkout API

Use the following Checkout API strictly for production transactions. Ensure that you never use these production URLs in the sandbox or testing environment

https://api.hesabe.com/api/checkout

checkout.php

    $baseUrl =  "http://sandbox.hesebe.com/api/";
    $CheckoutApiUrl = "{$baseUrl}/checkout"; 
    $requestData = [
        "merchantCode" => "842217",  // Sandbox
        "amount" => "100.000", 
        "paymentType" => "2", // Refer "List of Payment Types” Section
        "commission" => '0.500', // Total commission amount
        "responseUrl" => "https://sandbox.hesabe.com/customer-response?id=842217", 
        "failureUrl" => "https://sandbox.hesabe.com/customer-response?id=842217", 
        "version" => "2.0", 
        "orderReferenceNumber" => "9874659805", 
        "currency" => "KWD", 
        "name" => "customername", 
        "email" => "customeremail@gmail.com", 
        "mobile_number" => "66666666", 
        "variable1" => "First__variable", 
        "variable2" => "Second__variable", 
        "variable3" => "Third__variable", 
        "variable4" => "forth__variable", 
        "variable5" => "example.com",
        "webhookUrl" => 'https://yourdomain.com/example' 
    ];

Here's an subscription transaction parameters details

Field	Type	Description	Required
merchantCode	Numeric	Assigned by Hesabe	Yes
amount	Numeric	Amount in currency	Yes
commission	decimal	Must be between 0.000 and 100000.000 and Allows up to 3 decimal places only	Yes
responseUrl	Alphanumeric	Redirect URL on success	Yes
failureUrl	Alphanumeric	Redirect URL on failure	Yes
version	Alphanumeric	2.0	Yes
orderReferenceNumber	String	Your reference / order ID	Yes
paymentType	Numeric	Refer to the “List of Payment Types” section below for more information	Yes

List of payment types

Below are the available payment method options supported by Hesabe

Payment Types	Value
KNET	`"1"`
MPGS	`"2"`
CYBS	`"5"`
AMEX	`"7"`
MPGS AMEX	`"8"`
MPGS Apple Pay	`"9"`
CYBS Apple Pay	`"10"`
KNET Debit Apple Pay	`"11"`
KNET Credit Apple Pay	`"12"`
KNET Apple Pay International	`"13"`
AMEX Apple Pay International	`"14"`
Google Pay	`"16"`

Additional Checkout API Parameters

Optional parameters that allow you to include extra data or customize the checkout flow in your API request

Field	Type	Description	Required
name	String	Customer Name	Optional
mobile_number	Numeric (8)	Customer Mobile Number ( Without country code )	Optional
email	String	Customer Email Address	Optional
webhookUrl	String	Your endpoint for receiving payment status	Optional
variable1	Alphanumeric	Custom user parameter which will be included in the response when it returns	Optional
variable2	Alphanumeric	Custom user parameter which will be included in the response when it returns	Optional
variable3	Alphanumeric	Custom user parameter which will be included in the response when it returns	Optional
variable4	Alphanumeric	Custom user parameter which will be included in the response when it returns	Optional
variable5	String	Custom user parameter which will be included in the response when it returns	Optional

For Any Technical Assistance

If you encounter any issues or need support during setup or integration, please contact our technical team for assistance.

Hesabe IT Support

Email address:itsupport@hesabe.com

On this page