Direct Payment Method

This comprehensive guide will help you integrate your application or platform with Hesabe's Payment Gateway API, supporting multiple integration methods and advanced features.

🎯

Hesabe Direct Payment Integration

The merchant provides payment method selection (KNET, Visa/Master, American Express, Apple Pay, Google Pay) within their application interface, offering complete control over the payment flow and user experience.

✨ Features	Direct Integration
Complete control over payment forms	✅
Custom UI/UX design capabilities	✅
Higher level of customization	✅
Seamless brand integration	✅

✍🏻 Create a payment form in your application

Build a checkout page to get customer details such as order amount, currency, and customer information

📝 Collect payment details securely

Set up your merchant account and obtain your API credentials from the merchant panel to authorize API requests.

🌐 Send payment request to Hesabe API

Initiate a transaction by sending the order and payment details to the Hesabe API. Use our sandbox environment to test the integration flow, validate parameters, and simulate real payment scenarios before moving to production.

⏳ Process the response

Once the API responds, handle the payment result by validating the response data, verifying transaction status, and securely storing transaction references for reconciliation or record-keeping.

✅ Handle success/failure scenarios

Redirect customers to the appropriate success or failure pages. On success, confirm the order and provide a receipt. On failure, display an error message and allow the customer to retry or use an alternate payment method.

📋 Request Parameters

🏷️ Field	📋 Type	📝 Description	Required
merchantCode	String	Assigned by Hesabe	Yes
amount	Numeric	Amount in currency	Yes
currency	String	ISO currency code	Yes
responseUrl	String	Redirect URL on success	Yes
failureUrl	String	Redirect URL on failure	Yes
version	String	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	Alphanumeric	Custom user parameter which will be included in the response when it returns	Optional

🔄 Additional Parameters For Recurring / Subscription Method

Include these fields in checkout parameters when using recurring/subscription payment methods:

🏷️ Field	📋 Type	📝 Value	Description	Required
subscription	Numeric	1	Indicates that this transaction is part of a subscription/recurring billing setup	Yes
numberOfInstallments	Numeric	3	Specifies the total number of recurring payments (installments) to be made. In this case, 3 installments	Yes
recurringFrequency	Numeric	1	Defines how often the recurring payments should occur. `1` typically means monthly	Yes
recurringStartDate	String	2025-06-15	The date when the first recurring payment should start (YYYY-MM-DD)	Yes
recurringAmount	Numeric	10.000	The amount to be charged in each recurring cycle	Yes

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

⚙️ Additional Parameters For Authorization Method

Include these fields in checkout parameters when using authorization payment methods:

Important Note

Authorize features are only available with the MPGS payment gateway service

🏷️ Field	📋 Type	📝 Value	Required
authorize	Boolean	True	Yes

🔒 Additional Parameters For Capture Method

Include these fields in checkout parameters when using capture payment methods:

Important Note

Capture features are only available with the MPGS payment gateway service

🏷️ Field	📋 Type	📝 Description	Required
paymentToken	String	Payment Token returned from the authorized transaction	Yes

⚙️ Hesabe Request Handler

The following PHP Laravel code snippets demonstrate how the payment request process can be implemented.

Request Validation

First, validate the incoming payment request data to ensure all required fields are present and properly formatted.

Important Note

Payment data containing the required fields in encrypted form must be submitted to the 'Checkout' endpoint for initiating the payment request.

Checkout.php

$validator = $this->validate($request, [
    'merchantCode' => 'required',
    'amount' => 'required|numeric|between:0.200,100000|regex:/^\d+(\.\d{1,3})?$/',
    'paymentType' => 'required|in:0,1,2,5,7,8,9,10,11,12,13,14,16', // '0' For indirect method only  
    'responseUrl' => 'required|url',
    'failureUrl' => 'required|url',
    'version' => 'required',
    'webhookUrl' => 'https://yourdomain.com/example' // [Optional Field] To get transaction response
]);

Configuration Setup

Loading Encryption Keys, Access Code & API URL's from config

Checkout.php

$ivKey = HSB_IV_KEY;
$encryptionKey = HSB_ENCRYPTION_KEY;
$accessCode = HSB_ACCESS_CODE;
$checkoutApiUrl = HSB_CHECKOUT_API_URL;
$paymentUrl = HSB_PAYMENT_URL;

JSON Encoding

After validation, convert the request data to JSON format containing all the request keys and values.

Checkout.php

$requestDataJson = json_encode($request->input());

Data Encryption

Encrypt the JSON data using AES algorithm with the HesabeCrypt library for secure transmission.

Checkout.php

$encryptedData = HesabeCrypt::encrypt($requestDataJson, $encryptionKey, $ivKey);

API Request to Checkout Endpoint

Send the encrypted data to Hesabe's checkout API with proper headers including the access code.

Sandbox Checkout API

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

https://sandbox.hesabe.com/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/checkout

Checkout.php

$baseUrl = "https://sandbox.hesabe.com";
$checkoutApiUrl = $baseUrl . "/checkout";  
$checkoutRequestData = new Request([ 'data' => $encryptedData ]);
$checkoutRequest = Request::create($checkoutApiUrl, 'POST', $checkoutRequestData->all());
$checkoutRequest->headers->set('accessCode', $accessCode);
$checkoutRequest->headers->set('Accept', 'application/json');   // Only for JSON response

Response Handling

Process the API response and extract the content for further processing.

Checkout.php

$checkoutResponse = Route::dispatch($checkoutRequest);
$checkoutResponseContent = $checkoutResponse->content();

Response Decryption

Decrypt the response using the same encryption keys and parse the JSON data.

Checkout.php

$decryptedResponse = HesabeCrypto::decrypt($checkoutResponseContent, $encryptionKey, $ivKey);
$responseDataJson = json_decode($decryptedResponse);

Payment Page Redirection

Extract the payment token from the response and redirect to Hesabe's payment URL.

Sandbox Payment API

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

https://sandbox.hesabe.com/payment

Production Payment API

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

https://api.hesabe.com/payment

Checkout.php

$paymentUrl = {{baseUrl}}/payment
$responseToken = $responseDataJson->response->data;
return Redirect::to($paymentUrl . '?data='. $responseToken);

Sample Transaction Response Structure

Here's an example of a successful payment response after decryption:

{
    "status": true,
    "code": 1,
    "message": "Transaction Success",
    "response": {
        "data": {
            "resultCode": "CAPTURED",
            "amount": 10,
            "paymentToken": "1569830677725743478",
            "paymentId": "100201927384634224",
            "paidOn": "2019-09-30 11:05:16",
            "orderReferenceNumber": null,
            "variable1": null,
            "variable2": null,
            "variable3": null,
            "variable4": null,
            "variable5": null,
            "method": 1
        }
    }
}

Transaction Response Parameters Reference

Here's an transaction response parameters details

Field	Type	Description
status	Boolean	Payment status (true for success; false for failure)
resultCode	String	Success transactions have values "CAPTURED", "ACCEPT", or "SUCCESS"
amount	Numeric	Transaction Amount
paymentToken	Numeric	14-digit Payment Token returned from Hesabe
paymentId	Alphanumeric	Payment ID returned from Hesabe
paidOn	Alphanumeric	Date and Time of Payment
orderReferenceNumber	Alphanumeric	Payment ID returned from Hesabe
variable1	Alphanumeric	Custom user parameter which will be included in the response when it returns
variable2	Alphanumeric	Custom user parameter which will be included in the response when it returns
variable3	Alphanumeric	Custom user parameter which will be included in the response when it returns
variable4	Alphanumeric	Custom user parameter which will be included in the response when it returns
variable5	Alphanumeric	Custom user parameter which will be included in the response when it returns
method	Numeric	Transaction Payment method ID

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

Hesabe Direct Payment Integration

✍🏻 Create a payment form in your application

📝 Collect payment details securely

🌐 Send payment request to Hesabe API

⏳ Process the response

✅ Handle success/failure scenarios

🛒 Customer browses and adds items to cart

📝 Customer enters payment details

💳 Customer selects payment method

🔐 Payment data is encrypted and processed

✅ Customer receives payment confirmation

📋 Request Parameters

List of payment types

Additional Checkout API Parameters

🔄 Additional Parameters For Recurring / Subscription Method

Types of Recurring / Subscription

⚙️ Additional Parameters For Authorization Method

🔒 Additional Parameters For Capture Method

⚙️ Hesabe Request Handler

Request Validation

Configuration Setup

JSON Encoding

Data Encryption

API Request to Checkout Endpoint

Response Handling

Response Decryption

Payment Page Redirection

Sample Transaction Response Structure

Transaction Response Parameters Reference

For Any Technical Assistance

On this page