Subscription Method

The Subscription Method allows merchants to set up and manage recurring payments seamlessly. It ensures automatic billing at regular intervals, reducing manual effort and improving payment consistency.

Implementation Steps

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.

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" => "0.000", 
        "paymentType" => "15", 
        "subscription" => '1', 
        "numberOfInstallments" => '3',  
        "recurringFrequency" => '1', 
        "recurringStartDate" => '2025-04-15', 
        "recurringAmount" => '100', 
        "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' 
    ];

Types of Recurring / Subscription

🏷️ Types	Description
On-Demand Billing (recurringFrequency: 0)	Set `recurringFrequency` to `0` to configure an on-demand recurring profile. In this case, you will need to manually initiate the capture API each time you want to charge the customer
Auto-Capture Recurring (recurringFrequency: 1)	Set `recurringFrequency` to `1` (monthly) to enable automatic billing starting from the specified `recurringStartDate`. The system will automatically handle subsequent charges based on the configured frequency and installment settings

Here's an subscription transaction parameters details

Field	Type	Description	Required
merchantCode	Numeric	Assigned by Hesabe	Yes
amount	Numeric	Amount in currency	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	2 - ( Visa / MasterCard )	Yes
subscription	Numeric	Indicates that this transaction is part of a subscription/recurring billing setup	Yes
numberOfInstallments	Numeric	Specifies the total number of recurring payments (installments) to be made. In this case, 3 installments	Yes
recurringFrequency	Numeric	Defines how often the recurring payments should occur. `1` typically means monthly	Yes
recurringStartDate	String	The date when the first recurring payment should start (YYYY-MM-DD)	Yes
recurringAmount	Numeric	The amount to be charged in each recurring cycle	Yes

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