Integrating With Hesabe Payment Gateway Api End-point

Next Page: Direct Apple Pay Integration
Previous Page: Access Keys

INTEGRATION TYPES


Direct Integration

In this integration method, the merchant provides an option to select the Payment Method (Knet or MPGS) in the app itself. Based on the customer’s selection, the request param paymentType should be sent accordingly as described in the section Posting Payment Data.


Indirect Integration

In this integration method, the merchant does not provide an option to select the Payment Method (Knet or MPGS) in the app. Customers would be able to select their choice of Payment Method from the Hesabe Payment Gateway Landing page. The request param paymentType should be sent accordingly as described in the section Posting Payment Data.

Based on the selection of Payment Method here, the Customer will be redirected to the respective Payment page and Payment Type will be recorded by Hesabe.

The Hesabe Payment Gateway Page would look similar to as shown below: Hesabe Landing Page

POSTING PAYMENT DATA

Payment data containing the following fields in encrypted form need to be submitted to ‘Checkout’ Endpoint (https://sandbox.hesabe.com/checkout on Test and https://api.hesabe.com/checkout on Production) for initiating the payment request.


REQUEST PARAMETERS

Field Type Description
amount Numeric Amount must be greater than zero
currency String Currency ISO code
responseUrl Alphanumeric (200) Characters allowed: Alphabet (A-Z), (a-z), Numbers, / (slash),_ (underscore) Webpay will be redirected back to this url after payment completes
failureUrl Alphanumeric (200) Characters allowed: Alphabet (A-Z), (a-z), Numbers, / (slash),_ (underscore) Webpay will be redirected back to this url after payment completes
merchantCode Numeric Merchant Code is a unique identifier generated by Hesabe for each activated merchant.
paymentType Numeric 0: Indirect
1: Knet
2: Visa /MasterCard
7: Amex
9: Apple Pay
version Alphanumeric [10] Version of the API (example 2.0)
orderReferenceNumber Alphanumeric [100] Custom user parameter which will be included in the response when it returns
variable1 Alphanumeric [100] Custom user parameter which will be included in the response when it returns
variable2 Alphanumeric [100] Custom user parameter which will be included in the response when it returns
variable3 Alphanumeric [100] Custom user parameter which will be included in the response when it returns
variable4 Alphanumeric [100] Custom user parameter which will be included in the response when it returns
variable5 Alphanumeric [100] Custom user parameter which will be included in the response when it returns
name Alphanumeric [100] (*) Customer's name
mobile_number Numeric [8] (*) Customer's mobile number. Do not add country code with the mobile number.
email Alphanumeric [100] (*) Customer's email address
saveCard Boolean (#) Used to save card information for Tokenization using Cybersource. Need to ensure that name, email and mobile_number are sent when this is used.
cardId Alphanumeric [50] (#) Customer's card id. This data is fetched using Customer's card API. This should not be used along with saveCard
authorize Boolean (~) Used to authorize a transaction. Authorization hold (also card authorization, preauthorization, or preauth) is a service offered by credit card providers whereby the provider puts a hold of the amount approved by the cardholder, reducing the balance of available funds until the merchant clears the transaction (also called settlement).
webhookUrl String Your page url for receiving transaction updates. For more details you can check this link. https://developer.hesabe.com/docs/2.0/webhook-integration

{info} * These parameters are only used for KFast. If you want to enable KFast, Please contact your Account Manager or drop an email to support@hesabe.com.


{info} # These parameters are only used for Tokenization using Cybersource & MPGS. If you want to enable Cybersource/MPGS, Please contact your Account Manager or drop an email to support@hesabe.com.


{info} ~ These parameters are only used for Authorization using MPGS. If you want to enable it, Please contact your Account Manager or drop an email to support@hesabe.com.

Params - variable1, variable2, variable3, variable4, and variable5 can be used to pass arbitrary values (string only) in the form of key value pairs in the format "key__value". For example, to pass Customer Name in variable1, you can pass "Customer Name__John Doe" as value of variable1. These values would then be visible in the transaction details window of Merchant Panel and also be displayed in the email notifications.


The data is posted/passed to the HesabeRequestHandler that will concatenate and encrypt the data before invoking the Hesabe Checkout API endpoint.

1 .Purchase / Sales

Steps to integrate Hesabe Payment Gateway

  1. Sign Up with Hesabe and get a Merchant Account created and approved.

  2. Login to Merchant Panel using the credentials provided after Registration

  3. Download Hesabe Payment Integration Kit (on PHP Platform, other platforms will be added soon).

  4. Copy Encryption Key from Account section.

  5. Access Code & IV Key will be shared by Hesabe.

  6. Configure Hesabe security keys in your application.

  7. Create Payment form and deploy request / response handlers with the guidance of the integration kit.

  8. Create return pages for handling payment notification on success or cancel.


Download Hesabe payment gateway integration kit


The Hesabe payment gateway integration kit is a client library provided by Hesabe.

After Signing in with the approved Merchant account you can download the Integration Kit. From the Merchant Panel Dashboard, navigate through Resources > Download Integration Kit > Download PHP to get the integration kit for the PHP.

When you download the integration kit from the Hesabe merchant dashboard, it contains request response payment handler files. The integration kit also contains HesabeCrypto.php with the collection of functions to encrypt decrypt merchant data using AES-256-CBC.

Access Hesabe Merchant ID, Access Code and Encryption Keys

For implementing Hesabe payment gateway integration, the Merchant id, Access Code and the Encryption Keys (Secret Key + IV Key) are the prime information to be passed with the payment request. To get these, you need to have an activated Hesabe Merchant account.

After you login to Hesabe Merchant Panel using Merchant account credentials, you can see the dashboard with menu option “Account”.

Under Security Keys, it will display the Merchant Id, Access Code and Secret Key. IV Key will be shared along with the credentials to access the Merchant Dashboard after account activation.

Integrating with Hesabe Payment Gateway API end-point


Posting Payment Data

Payment data containing the following fields in encrypted form need to be submitted during Checkout for initiating the payment request.


Request Parameters
Name Description Condition Type/Length
amount Amount must be greater than zero Required Numeric
responseUrl Webpay will be redirected back to this url after payment completes Required Alphanumeric (200) Characters allowed: Alphabet (A-Z), (a-z), Numbers, / (slash),_ (underscore)
failureUrl Webpay will be redirected back to this url after payment is declined Required Alphanumeric (200) Characters allowed: Alphabet (A-Z), (a-z), Numbers, / (slash),_ (underscore)
merchantCode Merchant Code is a unique identifier generated by Hesabe for each activated merchant. Required Numeric
access_code Access code is used to revalidate a Merchant. To be used only for Indirect Integration. Required Alphanumeric[32]
paymentType Payment Type 0, 1 or 2; 0 - Indirect, 1 - Knet, 2 - MPGS Required Numeric
version Version of the API (example 2.0) Required Alphanumeric [10]
variable1 Custom user parameter which will be included in the response when it returns Optional Alphanumeric [100]
variable2 Custom user parameter which will be included in the response when it returns Optional Alphanumeric [100]
variable3 Custom user parameter which will be included in the response when it returns Optional Alphanumeric [100]
variable4 Custom user parameter which will be included in the response when it returns Optional Alphanumeric [100]
variable5 Custom user parameter which will be included in the response when it returns Optional Alphanumeric [100]

The data is posted/passed to the HesabeRequestHandler that will concatenate and encrypt the data before invoking the Hesabe Payment API endpoint.

Customer Details

To add Customer Details in the Transaction add below parametera to the Request

Parameters
name Alphanumeric [100]
mobile_number Numeric [8]
email Alphanumeric [100]

Webhook Url Response

To receive transaction reposponse add below paramter.

Parameter
webhookUrl String Url - POST Request

2. Authorize / Capture

Overview

The Authorize/Capture payment flow is a two-step process used in payment processing. It allows a merchant to authorize a transaction first, ensuring that the funds are available in the customer’s account, and then capture the funds at a later time when the service or product is ready to be delivered.

Authorize and Capture Feature is only available with MPGS payment gateway service*.

Authorize Transaction Request

To Authorize a transaction pass the below parameter while doing the checkout request

Parameter
authorize Boolean



Capture Transaction Request

To Capture the Authorized Transaction Send Post Request with below Parameters.

Parameters
merchantCode Merchant Code is a unique identifier generated by Hesabe for each activated merchant.
paymentToken Payment Token returned from Authorized Transaction
Amount Transaction amount equal to Authorized Transaction amount to less 
$baseUrl =  http://sandbox.hesebe.com/api/
$CaptureApiUrl = {{$baseUrl}}/capture
$requestData = [
"merchantCode" => 842217
"amount" => 10,
"paymentToken"=>84221717175011419773484853173
];
$encryptedData = HesabeCrypto::encrypt($requestData, $encryptionKey, $ivKey)
$checkoutRequestData = new Request([
            'data' => $encryptedData
        ]);
$checkoutRequest = Request::create($CaptureApiUrl, 'POST', $checkoutRequestData->all());
$checkoutRequest->headers->set('accessCode', $accessCode);

Cancel Authorized Transaction

To cancel the Authorized transaction for further Capturing the Amount.

$baseUrl =  http://sandbox.hesebe.com/api/
$CancelApiUrl = {{$baseUrl}}/cancel/{paymentToken}
$checkoutRequest = Request::create($CaptureApiUrl, 'DELETE');
$checkoutRequest->headers->set('accessCode', $accessCode);

3. Add Card / Merchant Initiated Transaction

Overview

The Add Card and Merchant Initiated Transaction (MIT) processes are essential components in payment systems, particularly for businesses that require recurring billing, subscriptions, or the ability to charge customers without their direct input at the time of each transaction.

Add Card

To allow user to add their card in your app or website create a checkout request with below parameters and let amount be Zero.

This Feature will only work with Cybersource Recurring Payment Gateway.

Parameters Value
paymentType 15
subscription 1
amount 0

Merchant Initiated Transaction

To Capture the Authorized Transaction Send Post Request with below Parameters.

Parameters Value
merchantCode Merchant Code is a unique identifier generated by Hesabe for each activated merchant.
paymentToken Payment Token returned from Add Card Transaction
Amount Any Transaction amount
orderReferenceNumber Custom user parameter which will be included in the response when it returns 
$baseUrl =  http://sandbox.hesebe.com/api/
$CaptureApiUrl = {{$baseUrl}}/subscription/capture
$requestData = [
"merchantCode" => 842217
"amount" => 10,
"paymentToken"=>84221717175011419773484853173,
"orderReferenceNumber"=>12365478989
];
$encryptedData = HesabeCrypto::encrypt($requestData, $encryptionKey, $ivKey)
$checkoutRequestData = new Request([
            'data' => $encryptedData
        ]);
$checkoutRequest = Request::create($CaptureApiUrl, 'POST', $checkoutRequestData->all());
$checkoutRequest->headers->set('accessCode', $accessCode);


Cancel Card


To cancel the Saved Card for further Transactions.

$baseUrl =  http://sandbox.hesebe.com/api/
$CancelApiUrl = {{$baseUrl}}/subscription/cancel/{paymentToken}
$checkoutRequest = Request::create($CaptureApiUrl, 'DELETE');
$checkoutRequest->headers->set('accessCode', $accessCode);

4. Refund

Overview

A Refund is a transaction process where a merchant returns funds to a customer after a payment has been processed.

Create a Refund Request

To Create a Refund Request for a Transaction pass the below parameters.

Parameters Value
merchantCode Merchant Code is a unique identifier generated by Hesabe for each activated merchant.
token Transaction Token of the Original Transaction
refundAmount Refund Amount
refundMethod 1 - for Full Refund , 2 - Partial Refund 
$baseUrl =  http://sandbox.hesebe.com/api
$RefundRequestApiUrl = {{$baseUrl}}/transaction-refund
$data=[
    "merchantCode" => {{merchant-code}}
    "token" => 521042117249344539468767555844
    "refundAmount" => 1
    "refundMethod" => 2
]
$checkoutRequest = Request::create($RefundRequestApiUrl, 'POST',$data);
$checkoutRequest->headers->set('accessCode', $accessCode);

Response Sample

{
    "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"
    }
}

5. Re-Query

StartFragmentIf you wish to enquire about a transaction status, after completion, you can do so by using the below information provided to you:

Request Parameters

Field Type Description
data Alphanumeric Data can be either Payment Transaction token or Order Reference Number (used in the request) to be passed in the URL.
NOTE: If you are using Order Reference Number, you are required to pass isOrderReference=1 in the body of the request.
accessCode String Access Code provided by Hesabe to be passed in the Headers 
$baseUrl = https://sandbox.hesabe.com
$transactionApiUrl = {{$baseUrl}}/api/transaction/{{$data}}
$transactionRequestData = new Request();
$transactionRequest = Request::create($transactionApiUrl, 'POST', $transactionRequestData->all());
$transactionRequest->headers->set('accessCode', $accessCode);
$transactionRequest->headers->set('Accept', 'application/json');
$transactionResponse = Route::dispatch($transactionRequest);
$transactionResponseContent = $transactionResponse->content();

Response Sample

{
    "status": true,
    "message": "Transaction found",
    "data": {
        "token": "521042117249344539468767555844",
        "amount": "45.000",
        "reference_number": "1724934434",
        "status": "SUCCESSFUL",
        "TransactionID": "424210001296274",
        "Id": 129179,
        "PaymentID": "100424210000015649",
        "Terminal": "144301",
        "TrackID": "25119",
        "payment_type": "KNET",
        "service_type": "Payment Gateway",
        "customerName": "User Name",
        "customerEmail": "user@gmail.com",
        "customerMobile": "98726012",
        "customerCardType": null,
        "customerCard": null,
        "datetime": "2024-08-29 15:27:38"
    },
    "results": [
        {
            "token": "521042117249344539468767555844",
            "amount": "45.000",
            "reference_number": "1724934434",
            "status": "SUCCESSFUL",
            "TransactionID": "424210001296274",
            "Id": 129179,
            "PaymentID": "100424210000015649",
            "Terminal": "144301",
            "TrackID": "25119",
            "payment_type": "KNET",
            "service_type": "Payment Gateway",
            "customerName": "User Name",
            "customerEmail": "user@gmail.com",
            "customerMobile": "98726012",
            "customerCardType": null,
            "customerCard": null,
            "datetime": "2024-08-29 15:27:38"
        }
    ]
}

HesabeRequestHandler

The payment data posted/passed via the checkout form is handled by HesabeRequestHandler. The posted data are first validated and encrypted in this file. The Encryption key and IV (Initialization Vector) taken from Profile page of Hesabe Merchant dashboard are used as the encryption keys.

The following sample PHP code snippets demonstrates how the process can be implemented in PHP Laravel.

Validation

$validator = $this->validate($request, [
            'merchantCode' => 'required',
            'access_code => 'required', // Only for Indirect Integration
            'amount' => 'required|numeric|between:0.200,100000|regex:/^\d+(\.\d{1,3})?$/',
            'paymentType' => 'required|in:0,1,2',
            'responseUrl' => 'required|url',
            'failureUrl' => 'required|url',
            'version' => 'required'
        ]);


Loading Encryption Keys, Access Code, and API URLs from Config 

$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, the request data is JSON encoded which is the array of the request keys & values.

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


Encryption

This JSON data is then encrypted using AES algorithm with HesabeCrypto library

$encryptedData = HesabeCrypto::encrypt($requestDataJson, $encryptionKey, $ivKey)


Invoking Hesabe Payment API “Checkout” endPoint

The accessCode is initialized in the Request header and the Request data is posted to the Hesabe Payment Gateway Checkout API endpoint.

$baseUrl =  http://sandbox.hesebe.com/api/
$checkoutApiUrl = {{$baseUrl}}/checkout
$checkoutRequestData = new Request([
            'data' => $encryptedData
        ]);
$checkoutRequest = Request::create($checkoutApiUrl, 'POST', $checkoutRequestData->all());
$checkoutRequest->headers->set('accessCode', $accessCode);


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


Decrypting Response & JSON Decoding
$decryptedResponse = HesabeCrypto::decrypt($checkoutResponseContent, $encryptionKey, $ivKey);
$responseDataJson = json_decode($decryptedResponse);






Next Page: HesabeRequestHandler
Previous Page: Access Keys