Subscription invoice
Generates a new subscription-based invoice for the merchant with customer details, subscription plan, recurring amount, and payment configuration. The request payload must be sent in encrypted format
AuthorizationBearer <token>
Pass access token obtained from login endpoint
In: header
Header Parameters
accessCodestring
Pass the merchant access code issued by Hesabe
Acceptstring
application/json
Content-Typestring
application/json
datastring
Convert payload JSON object to encrypted string and send it to the server
Sample Encryption and Decryption Process:
The following steps demonstrate how to integrate with this API using sandbox credentials.
Step 1: Create JSON Object
{
"merchantCode": "842217", // Pass the merchant code provided by Hesabe
"mobileNumber":"66666666",
"customerName": "TEST",
"referenceNumber": "1234",
"amount": "80.000", // Pass three decimal value
"countryCode": "965", // Mobile number country code
"invoiceType": "0" , // Invoice type "1" for "SMS" and "0" for URL, Whatsapp, Email
"invoiceSubType": "3", // "0" - SMS , "1" - WhatsApp, "2" - Email, "3" - URL
"description": "Invoice testing",
"allocatePayType":"1,2", // (Eg - "1" KNET, "2" - MPGS etc)
"subscription": "1", // "0" for Quick invoice , "1" for subscription invoice
"expiresAt": "2026-12-12", // invoice expiry date
"frequency": "1", // Monthly
"noofRecurrence": "1", // No of recurrances
"SubscriptionType" : "1", // subscription Type - "1" - On Demand" , "0" - "Auto Payments"
"startDate": "2025-02-12" // subscription start date,
"webhook": "https://yourdomain.com/example" // Add your Webhook URL"
}Payload Details
Contains the list of parameters and their corresponding values required to make the API request.
| Field Name | Description | Required |
|---|---|---|
merchantCode | Pass the merchant code provided by Hesabe | Yes |
mobileNumber | Pass the customer mobile number | Yes |
customerName | Pass the customer name | Yes |
amount | Pass the invoice amount | Yes |
countryCode | Pass the mobile number country code | Yes |
invoiceType | "0" - URL sharing, "1" - SMS invoice | Yes |
invoiceSubType | "0" - SMS, "3" - URL | Yes |
allocatePayType | Pass the selected payment method numbers (e.g., 1,2,5,10) based on the Hesabe payment gateway subscription. Refer to the “List of Payment Types” table below for detailed information 👇 | Yes |
expiresAt | Pass invoice expiry date "YYYY-MM-DD" | Yes |
subscription | Pass "1" for subscription invoice | Yes |
frequency | Pass "1" for monthly subscription | Yes |
noofRecurrence | Pass the value to capture number of times. Eg: "1" time in a month | Yes |
SubscriptionType | "0" for "ON Demand", merchant needs to capture through API "1" for "auto payments", Hesabe will capture based the date & number of recurrence | Yes |
language | Defalut is "en" and for arabic invoices "ar" | Optional |
description | Pass invoice description details | Optional |
webhook | Pass your webhook URL | Optional |
itemsList | Pass product details in array of objects, products total amount should not be less than total invoice amount. Check below for more details 👇 | Optional |
Sample "itemsList" payload
[
{
"itemTitle": "Iphone", // product name
"rate":"120.000", // unit amount
"quantity": "1", // product qty
"amount": "120.000" // Final amount
},
{
"itemTitle": "Iphone 13", // product name
"rate":"160.000", // unit amount
"quantity": "1", // product qty
"amount": "160.000" // Final amount
}
]List of invoice sub types
| Types | Description | Value |
|---|---|---|
| SMS | Send an invoice link to the customer via SMS | "0" |
| URL | Copy and share the invoice link through any platform | "3" |
List of payment types
| Payment Method 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" |
Step 2: Convert the JSON object into an encrypted string format and post to Hesabe
{
"data": "0e7898bd7464d0c402fe8a949d9cbf9b64a98634a092ee6261f9f3d288eb01a442a32ba890f3e1db57ebd53c63045f936f182ae1c3cbec0508f473bb7f3b24bf941a5f2b665796cf68b949adb85b9d0f6ae5d0f37bd93608089b5f2a5b46df71fbf8945071bb4e23e6e863549db0d6151ec894086e8e4580e67eedb2c3aa137bd0bfef133ca86e6043123d96e184edd970597243df61c6c7799b30b49fd15d6bbe7dde24c60fac68129ceacc6b258a178c27e9589b5e2ca52d276081a0afb576b59857a94a18adcb6f7835d793b29bc2c32e2dd3adaa47c242404c56a6cbd83d4e27b534bedbda1d4854e299136ced154875b83295061d8e23f95350e56c43226013876ec27e9d2681a7751834c9d52a1ef1473a1601289cc3ccb3a2bfe7d75ac94bf4f42b5611ce010f6de37ff8654f83927a68b47a7fee192d69dcc41413c76e78c841efe436f52089529139c4fd4a99df0d8e2c980c4ea8694e8beacc0c4643aa6da1ea0734653afa3189d819ddeb"
}Step 3: Receive encrypted response from Hesabe:
{
"response": "60a8f6241932227b840a9f5e36987f4d894e5813e1ec714a9f1093832ea77937e6611102e7fb85a9c6b25a3c5fdf4ef16077ffcdcbfd043049cde6c2bcca3061965b341c00323db25f7ac1ad9505ae8d9e1ecf3734f146376ca4e302c4cfcf47905a28b343372798a6ad62264283b0b66f3d47537bcd8922737a1c0b890e4fe79b9c5e91385d39f63c76460677cbdda1a1281f13b26a51d1237737b12302e54fe0f8988afab743ad0c1cea9cb9b63fe4e8e1388b5354057b54e9cf7247c6516484797c90476d99aae8ac7e33583608a589c53e04e15969706dd3944ed74960d3bf517207e209f51a50a4e690415181a98803b781bd648d9bad5e7eeaab6ea683593f034f10a37bbdbf3217d4142510723cd85cc331c975e9b3e0807567711fd0523ed65f119f16928d2776aa727e038d02ff192a2025737769793c3e3a9da270d8de0047bb4ebb71e3863af337dc8f9ea9dfd751ed5720123bbf991fa9d03e806ecbcd6f4b710b8305fd1f5a0715f411ddab6698fdbd4a4e683eda7a7612edab7f003d25b5d5490bf5ae736246ea55a73d7f09487ef1ad5c21f6611a47300b96baf5c5b2f5db146da2bbcb69d212a7af371208957ef2587c2ce8abd079322b0a26f832deac044367aac77b322e72cd47e2c7fb44a6cc58d539170abb5bf5178d35704a33f5a95cf26a5b6e7f8bf74d172807c1bf6717bf76d8290d527d92baa50d324ab4a61b32fd47a18e087ac16fa7df1d8183a54ff274ef55dad074ead3b6eb23050549c4c60e33ea721f0b2a992acfd3784b8c40e627ea81400697dc873737bbb8e1e0c1b75355a6d914dcc7aa4a9477bb48a558e5e000d9988702738b56fefa7205d2940cde5ac889f405e6024f2219208ad6346f1b59422de5ba1704a144747831ba081567d1fb542e7a93e01e909daace27e516088d83a896d85b1a6d5d97eabc5083170381bdbe31550b3c955a9a654b219878fea315f122fc41b1864d5ebd942a05bd9734c28bcb24e350aa60c0fb38dca1c1e176511a5763b28b899a1937404cf3a89aee429ed17b69045930a77ed309e76565cd72330fa348ca1a54f695cf6a7a4d06bc588e7f6273c96bce92481072c2881a82d43114164398117b3b0be1bc0068b75ac74b0c0ed8e6dcfb93faef6006c4ca2c4da6ae312903b2cf6f4f937a8778550860996b9d251b396d92a799813591aeef94818b8543efdae308774c7d5aa173777f9dfa1355104cc1c7c68cb57b3560b6ff9e2074f5668b61b2d75abad3b2fbb7006093ca17e075951e8570ba20507521017ebe07e50f0e514f3583bce1e0e79cf3738c73e64b557e514263f7b147c4be456423036766172c21689918ab97adc7dbf80c4e92e0583471f31f3be2f98711427e44a6de5a2663ce3060aee0cb27d5e1b6330074ea4389e23d8b58800c3b002228ea127dd0cb070f59cef11231218ddabf5de77613e389b5c7d77fedb5d87dfaca90e2f00fad55dec9f4b1f099949cdacf9118136d9679639c3ac4724da75d4e91d1d874c00033cab3c68fe55874e395fbb286f90c9f920155cb5cb3cd80a1d008ebab908296cda9547860dfc9b584421092a847a9af62683e2ed3895fa4b8fb55733f284b257a5e8bb68dbe63a3bb173fbfd399768ae1c37b476e5ded0c51e4b458418fc587abf92c60a20ae742b44aa894c66d46f755ed589f9a958e16265de932854008598dd7efa189fc2f376aa4bbd13fc9fd8e5406876f90112536411416fa6422a71dd0748394190c6f44f5528e59b4899b89a8378b004c33092411fe220348e36e1b20749b8a037e62a0630f293daaf7d54ed4d14d627ac005a950e3379a5c932303a03b8f297e312d6dfb132e00439c5ae5c2169fe6749eb76e525e2b7d541cf0180674bcaafde80dfe533a16fd07a111ddbaa8cecb4dae5807050dfbb8158a3bc947717973ac6e4b727373503711ee0a77a0d79d5ddc79616855176022aca3db8f3c2f4676263bda39e860d6c72c91e5eeaed749de6a0e99fe380a5f13ad4877d53e5bbf7648f1617d1296e59a5e620ec348436b6745d578df34366b4834b1b3d156f12bcd4460542296a7590238dc4cc5f3ba68f41a1cdf527fc9d18b342d0345c98c5d69b770718f8c26a3ed7f10769b3241a77ea004f38367a966f855190da06ab1c7a58a3775248c199027c267cd3b3ef03abd966a5ea53fe3a96443b01084e78424007b3a1199dfbbde319f3e685421c9c8d692ce2d9c89091b9fc74add9066d21766eb24bff3b388f321e7596bbd048d011ecb0f68bd72857aca1a766ec3"
}Step 4: Decrypt the api response and view the JSON output
{
"status":true,
"message":"Invoice generated successfully",
"response":{
"id":14714,
"invoice_type":1,
"invoice_sub_type":"3",
"token":"84175982518093871998",
"access_key":"96W66ER9",
"split_access_key":"",
"merchant_id":84,
"reference_number":"1234",
"amount":0,
"service_charge":"0.000",
"payment_method":[
"15"
],
"discount":"0.000",
"description":"Invoice testing",
"sms_response":"",
"invoice_status":null,
"subscription":{
"id":609,
"customer_phone":"66666666",
"customer_email":"",
"payment_type_id":15,
"service_type_id":2,
"amount":80,
"reference_number":"84175982518093871998",
"frequency":"Monthly",
"status":3,
"start_date":"2025-02-12 12:00:00",
"number_of_installments":1,
"next_billing_date":"2025-02-12 12:00:00",
"type":1,
"created_at":"2025-10-07 11:19:40",
"updated_at":"2025-10-07 11:19:40"
},
"sms_status":0,
"url_status":1,
"visited_count":null,
"country_id":11,
"created_id":84,
"language":"ar",
"expires_at":"2026-12-12",
"attachment":"",
"url":"http://demo.hesabe.com/s/96W66ER9",
"spliturl":null,
"created_at":"2025-10-07 11:19:40",
"updated_at":"2025-10-07 11:19:40",
"en_sms":"Hi TEST , \r\nYour transaction amount is KD 0 with the ref no : 1234 . Review and pay at",
"ar_sms":"hi TEST,\r\nمبلغ الصفقة هو دينار كويتي 0 مع المرجع رقم: 1234. مراجعة وتدفع في",
"customer":{
"name":"TEST",
"email":"",
"phone_number":"96566666666"
},
"created_by_merchant":{
"id":84,
"name":"test"
},
"products":[
],
"transaction":null
}
}Response Body
application/json
application/json
application/json
const body = JSON.stringify({ "data": "0e7898bd7464d0c402fe8a949d9cbf9b64a98634a092ee6261f9f3d288eb01a442a32ba890f3e1db57ebd53c63045f936f182ae1c3cbec0508f473bb7f3b24bf941a5f2b665796cf68b949adb85b9d0f6ae5d0f37bd93608089b5f2a5b46df71fbf8945071bb4e23e6e863549db0d6151ec894086e8e4580e67eedb2c3aa137bd0bfef133ca86e6043123d96e184edd970597243df61c6c7799b30b49fd15d6bbe7dde24c60fac68129ceacc6b258a178c27e9589b5e2ca52d276081a0afb576b59857a94a18adcb6f7835d793b29bc2c32e2dd3adaa47c242404c56a6cbd83d4e27b534bedbda1d4854e299136ced154875b83295061d8e23f95350e56c43226013876ec27e9d2681a7751834c9d52a1ef1473a1601289cc3ccb3a2bfe7d75ac94bf4f42b5611ce010f6de37ff8654f83927a68b47a7fee192d69dcc41413c76e78c841efe436f52089529139c4fd4a99df0d8e2c980c4ea8694e8beacc0c4643aa6da1ea0734653afa3189d819ddeb"})fetch("https://merchantapisandbox.hesabe.com/api/v1/invoice/", { method: "POST", headers: { "Content-Type": "application/json", "accessCode": "c333729b-d060-4b74-a49d-7686a8353481", "Accept": "application/json" }, body}){
"status": true,
"message": "Invoice generated successfully",
"response": {
"id": 14714,
"invoice_type": 1,
"invoice_sub_type": "3",
"token": "84175982518093871998",
"access_key": "96W66ER9",
"split_access_key": "",
"merchant_id": 84,
"reference_number": "1234",
"amount": 0,
"service_charge": "0.000",
"payment_method": [
"15"
],
"discount": "0.000",
"description": "Invoice testing",
"sms_response": "",
"invoice_status": null,
"subscription": {
"id": 609,
"customer_phone": "66666666",
"customer_email": "",
"payment_type_id": 15,
"service_type_id": 2,
"amount": 80,
"reference_number": "84175982518093871998",
"frequency": "Monthly",
"status": 3,
"start_date": "2025-02-12 12:00:00",
"number_of_installments": 1,
"next_billing_date": "2025-02-12 12:00:00",
"type": 1,
"created_at": "2025-10-07 11:19:40",
"updated_at": "2025-10-07 11:19:40"
},
"sms_status": 0,
"url_status": 1,
"visited_count": null,
"country_id": 11,
"created_id": 84,
"language": "ar",
"expires_at": "2026-12-12",
"attachment": "",
"url": "http://demo.hesabe.com/s/96W66ER9",
"spliturl": null,
"created_at": "2025-10-07 11:19:40",
"updated_at": "2025-10-07 11:19:40",
"en_sms": "Hi TEST , Your transaction amount is KD 0 with the ref no : 1234 . Review and pay at",
"ar_sms": "hi TEST, مبلغ الصفقة هو دينار كويتي 0 مع المرجع رقم: 1234. مراجعة وتدفع في",
"customer": {
"name": "TEST",
"email": "",
"phone_number": "96566666666"
},
"created_by_merchant": {
"id": 84,
"name": "test"
},
"products": [],
"transaction": null
}
}{
"status": false,
"message": "Request not found, Please verify the request data",
"response": null
}{
"message": "Internal server error occurred"
}