Split invoice
Create a split invoice so that the payment can be collected in separate installments or by different payers
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", // Merchant code
"invoices": [
{
"amount": "100.000",
"expiresAt": "2026-12-12",
"referenceNumber": "8849404",
"merchantCode" :"842217",
"invoiceType": "1" , // Invoice type "1" for SMS invoice and "0" for URL sharing
"invoiceSubType": "0", // "0" - SMS , "1" - WhatsApp, "2" - Email, "3" - URL
"language" : "en", // "en" for english , "ar" for arabic
"description": "test",
"customerName": "Mohammed",
"mobileNumber": "66666666",
"countryCode": "965",
"customerEmail": "test@gmail.com",
"allocatePayType":"1,2" // (Eg - "1" KNET, "2" - MPGS etc)
},
{
"amount": "150.000",
"expiresAt": "2026-12-12",
"referenceNumber": "88445604",
"merchantCode" :"842217",
"invoiceType": "1" , // Invoice type "1" for SMS invoice and "0" for URL sharing
"invoiceSubType": "0", // "0" - SMS , "1" - WhatsApp, "2" - Email, "3" - URL
"language" : "en", // "en" for english , "ar" for arabic
"description": "test",
"customerName": "Mohammed",
"mobileNumber": "66666666",
"countryCode": "965",
"customerEmail": "test@gmail.com",
"allocatePayType":"1,2" // (Eg - "1" KNET, "2" - MPGS etc)
}
]
}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 |
customerEmail | Pass customer email address | Optional |
language | Defalut is "en" and for arabic invoices "ar" | Optional |
description | Pass invoice description details | 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": "0e7898bd7464d0c402fe8a949d9cbf9b36e81fdd93ada05447ec483d9853a1a47b4d96436827b2d95b63116682b51bb848ab497e60c398fc8a22f92af333853d8f5edacaf6ffdf7adcc8fedb7dc0e54cb9ceaa09c25d883a3a50d12bd38f238f5345fefe7b24254deb16ee2a45bc009298173fe838fa404de69baf2b9cf087142ffe485b06e651b8052c1974fd0bd54c4ab8af5bc04b7443b50cbab6ea0a861c4d04069004558816123b46becb2eaa2d13b37e67d28b525bf04330f5606a431f461d5f55d90846c032fb7463ad9991961d8585cb2bb231c63de269d6e4ae158b24b09c8625a3c812dd0023847a904b63c503a05bbacf30d56bacec9cbbd86e131deff37ce016dc366841ce279452b19a77bcf12cc337b1569ecc9f9090f050b8d589b24c07217fc0d272e8ce5fb552f1e5635539801cd2615e5677c64fd3c252bc646b13ac0a56c53d2d40367424879070c1a2128d6132e17a09fc0aca3a60db8614fdb6f145f502e013b5e85e114544d54ff362018f3bf72e4e5a08e6f2078f37d7084884e6bca8f887a2e637e44924083f9e5d198c6f0530fe632451868fdb48befb423c19d6af430db9964442c760b35f0f5a4a7ae25986141f9ab43b80cfdbbc7c22ee4df0031791936d74bdd8b1961888aa2e8b05da491f9cd9eafee0ed7d1711d1c538de30d4c03e25a444cbc6df4c48948aa2dd6216fd8a33bf8155cac113f5933a6ecbde8e842073da97dbfbb3b96bed2549d4b39c93c3ca347af8ef70d2f87df6d21da7df8e95628a0318c28842d5c74600dabad69cb164d68a785757cb50c29bcd340996ed854d1668f2cae21fe2da49fcecc9c54ea3ab8c28cfc44398b3d13dd856fb4593bccc75fa6e3413391e01665dceba58b6ae4af984e7500fd56894b259d74972073daa5bc57b78"
}Step 3: Receive encrypted response from Hesabe:
{
"response": "60a8f6241932227b840a9f5e36987f4d894e5813e1ec714a9f1093832ea77937e62bab06bd7f6d1f6c96864648eb00dab19d8a3cf8fcbe02ca678f6459ffa0801f57243bec0a13f37136aae4a5519e5818b40532312965792af15c7e146208a4bff424a1e094cabb7b36c4c11a452892bbe54ef866ba648e1629e201ccff341e6a3cccbe2bdf77d1c662cfe160544d83308814a75f41c9408a1a88a72d181cf0820d07af7d7a73c6b697ec81882c2be81601c95577104463765dc6042795ea4a9bd99eb42edcccdce7cc8cb400e32e87a13563346c6e3650a2ff2c36ab7e575a57eb480454a941fa28c77e2495debbd91f1e3d82ca768e6964ac400ccc8fa20e2fa147216585e9eaa4cb5af8795755e78cd86599861ba382bb8f8cc62aa5bda9d43c376094c5867e436e49af281c62887b853b8d90fa4d6ee4d03239d5fdce01c86dc6005d113fd533d33da6ca8ad65c763c652bef03eae3c928573fc29e24a9a90e4c8e1406caecd1adea0c3533bb0dcce9bf87d7e20cbfc0dd0f1456471abe4624f1e68cefce541ec98f9180bac34ae0182583a4951e68a0f69110e6b367d5ca541c36309c336a61d91fdab177ba89ea94fb8ccd0785800536eb72ceb8c46e24455224900364f428a1de92eb6361b6e896ba1fff7a0f71684676fe07c6e95cebe73b6128c3895f36defb4850cbbd8f50aaf66e4209c18416d4d848974ad05d5f6e446dbc318c20e440f2e73a28ed4841dd02291aa5bff4f0f90191d4e9a02fa8acd137101de36b4ed50b9c6a19383b1485eed968348775e79feb7b61796d2ed4ce478284253816fc3c39cf464e2a0678290d191e0f37de31aa9a76f388921d84c3666773bbd08801069e9d1999a1ef9881b04917df8d5a8587cae4dcdce60208d58185d84554c7d6f00105c58f520dd27b336c4b9d3404489a71f10d47f0f8d0e18244919de99aae4b5fdabe13cbe83dc11de3a191afde040afa0c3e0038afb19c6d20613f5995c87a5df5ec0a7d9ba9037cf3cfc8531b8c296ce3224a38c9ad42b4426341c6773ec5a6765c99f908f9484057de7f76f2ba4db27950baedf3eb78f4df0c82e4345859d7cf0dfe35f8542f1579ac42daa178d2e6347323c4fd0bf8e086e84a7e70a7b20ea4c2bf74385788b91b1b4250b120bcf4844faf5c1b9c131cb950e7f8ed4b2bcacbcdb34a28897d38101904e107e7c6a269e5bceafff0e5ead61ee7cde0660fbe90922c69b1a818a25d8c716171ac0d0c3dae8a235a8eb00b898691bdedf91a71c4e34a16f29574e8ddfddfe729d15c22ee16a2f91ebd71f83255a3f042af6e1b8729d4b3801ad4f400b003f52f02c2a65f87ed7f718d63b2546285794d52d8b7823524348039cc818efde6d90fe5f317c02cbdfc4cdbb89f1dffe9f6dea5bceba9e7d2b6384f18dfd651329de50e5cb8be78dab287fed71a8dfc5f911b2d734d17c77bab3ebfbc6354f7de7aaf77811b172b2a2eb93f4887ca3d780b5c6f3ab0edd6e34482aa53067a8d32b8c2b0889bd0b02d82caa8de8bdb9009c08e7769cbf82874e1837b2965f665de895a2098c81abe18410c077808abf0563f5cb77d6fcd0c174f6862ec8e5a91c97f54194cd49d5ece165dcd6ca1a7a6fccd5136fe31a671a3eff94060d5549e7934de2d04b4e00775c3f8efa5245cc3b4a2ce3a454111d0bcdc2d46947fea4544956a545cf839177b5dcdadf6a6c3b80f0fc2d41b22ff3d04f6984ebf8b0df579b740261156e58f33e23f7c71f8ef91eafd70c64406cc19ae525db065d4a2fa04133309a1fc9f42380fb94361676db8d799bd98d9694b675acb5c7048b6cc04329790e6baf4f8cb413c7c7cce649e38fe18cf39cbe5d7bd58cd8562d247cc452e4c81b986ee4a18c162f978c78b0cd0ffca7aa3cc5953ea0c3af8a8864d49f36f8507368e40b4a6658a51bd7ee955dc500f9d53f67394bb3be06cffda03e26674d35dd69367a3dd3d8a0fbe4e8bf810a4bbb81eb38d5ffae1422cee456c8b1662b4c4505ed0c84a53884f24eb81f4d6ca023c9d57dfc869dfa042e3f0e2881d3a60c9182a1359ce5b10320d3567f41f7c5bb5afb26a798757444dff79aba8e12bbe490fc46169eeb6329452161fe6f04bdd1855b2a4143d92ef2fcf0e24d6ac7e2dd62f0c949c0f3559c527e905aa1f76db6066930a5b1f77d2aaf3deb9bf0d0b3789550c2168ee69eacfc9caed2da39f2f9f843fe4746b94a224db35ea098862cf38926d2df06829fd9b58d006ab65e205630d842566c2327a2d6397bafadaacc96b206b3d871e6b205b7f035f7e439125caee362e39656924f3bcaeaf0521df07b3e8c2d4120d3ad1e647bbea17ec42075f1477007dae97896e5dddfffccdf4350adee630a14c020977e0193f47210720f8d1aacdaf33a3c6d4522384a52d8f78351a17f79b6a7ab4790caedaa0d9fc7066143f0bd82e4576c94b055fc279e75890a0d66568a0dccb9ecc55b46b43e0988c6807ead386c0933382931b334e92ad8eab9ee14767d32233ff71d62079dfac5bd23fe493840cd186df1207793ce21cd40f124ad8d28a9efe"
}Step 4: Decrypt the api response and view the JSON output
{
"status": true,
"message": "Invoices processed successfully.",
"response": [
{
"id": 14726,
"invoice_type": 6,
"invoice_sub_type": 1,
"token": "841759836755946496641",
"access_key": "977YY8Q9",
"split_access_key": "SP977YY8Q9",
"merchant_id": "84",
"reference_number": "8849404",
"amount": "100.000",
"service_charge": "0.000",
"payment_method": [
"1",
"2"
],
"discount": "0.000",
"description": "test",
"sms_response": "",
"invoice_status": 0,
"subscription": null,
"sms_status": 0,
"url_status": 1,
"visited_count": 0,
"country_id": 11,
"created_id": 84,
"language": "en",
"expires_at": "2026-12-12",
"attachment": "",
"url": "http://demo.hesabe.com/s/977YY8Q9",
"spliturl": "http://merchant.hesbstaging.com/sp/SP977YY8Q9",
"created_at": "2025-10-07 14:32:35",
"updated_at": "2025-10-07 14:32:35",
"en_sms": "",
"ar_sms": "",
"customer": {
"name": "Mohammed",
"email": "test@gmail.com",
"phone_number": "96566666666"
},
"created_by_merchant": {
"id": 84,
"name": "test"
},
"products": [],
"transaction": null
},
{
"id": 14727,
"invoice_type": 6,
"invoice_sub_type": "1",
"token": "84175983675597391317",
"access_key": "953668Y9",
"split_access_key": "SP977YY8Q9",
"merchant_id": 84,
"reference_number": "88445604",
"amount": "150.000",
"service_charge": "0.000",
"payment_method": [
"1",
"2"
],
"discount": "0.000",
"description": "test",
"sms_response": "",
"invoice_status": null,
"subscription": null,
"sms_status": 0,
"url_status": 1,
"visited_count": null,
"country_id": 11,
"created_id": 84,
"language": "en",
"expires_at": "2026-12-12",
"attachment": "",
"url": "http://demo.hesabe.com/s/953668Y9",
"spliturl": "http://merchant.hesbstaging.com/sp/SP977YY8Q9",
"created_at": "2025-10-07 14:32:35",
"updated_at": "2025-10-07 14:32:35",
"en_sms": "",
"ar_sms": "",
"customer": {
"name": "Mohammed",
"email": "test@gmail.com",
"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": "0e7898bd7464d0c402fe8a949d9cbf9b36e81fdd93ada05447ec483d9853a1a47b4d96436827b2d95b63116682b51bb848ab497e60c398fc8a22f92af333853d8f5edacaf6ffdf7adcc8fedb7dc0e54cb9ceaa09c25d883a3a50d12bd38f238f5345fefe7b24254deb16ee2a45bc009298173fe838fa404de69baf2b9cf087142ffe485b06e651b8052c1974fd0bd54c4ab8af5bc04b7443b50cbab6ea0a861cf4410dc55cc807725815b45222df391046ba3b4814467a123595ddf4cd9aff910d0b2f3cc5f2b448849179594b1d33e2faf471666fa1d2c79dd9c55e9293e43d09c7052973117d404508030f8010503a0d67dec2bf8f9d87bae7430282f262a46b525298ff2132780b41e17928ffd5a62829a763020da05ab4b0f1efcb968a35ff9b59da559928b5ada9941bce7083287049351d4048304fce1e75902d2eec5a4809de6fd51e0ec0cbf4d7fb332b7bdbb6b562ff5eaac32d648585a9c9df4c9125d042a142be45e535e5b1ca320520d84f52e9b50344110d664a72b9c209b78b9cfcdb87464bea8cbacbb66040d4ffd7a56a38e059a955a70be941cbd2b8bf37b798afc279adfdb10094b2de8322ec351951b9ede867673f1ded58a387a5583afcf3ab85d886d7fe980b2daed1f99e6e99a98e8804b7dae8a417cf8e10051dfb977fff6a9b6b1166c2f654c8af02db84032af72133982597373683bbb3fd7bc526cbd4da727f1635fa0504aae38ca81666f6bec4951e37d1215a18fedc1e923a0c18dea995ae96241e1fde9c8718afa0e26cabd127ae3d80e3db532494b4425fb086530d8038f24eb4afb9b29ad2f0355cc2c546fe4a82ceb0691a4069f8e886c5949f1e41fb93453cc364d6d609304cd14c32951bbb72e3a73346b0e8019f3f35499fb8c2048d603ccbf1f49739e853"})fetch("https://merchantapisandbox.hesabe.com/api/v1/invoice/split", { method: "POST", headers: { "Content-Type": "application/json", "accessCode": "c333729b-d060-4b74-a49d-7686a8353481", "Accept": "application/json" }, body}){
"status": true,
"message": "Invoices processed successfully.",
"response": [
{
"id": 14726,
"invoice_type": 6,
"invoice_sub_type": 1,
"token": "841759836755946496641",
"access_key": "977YY8Q9",
"split_access_key": "SP977YY8Q9",
"merchant_id": "84",
"reference_number": "8849404",
"amount": "100.000",
"service_charge": "0.000",
"payment_method": [
"1",
"2"
],
"discount": "0.000",
"description": "test",
"sms_response": "",
"invoice_status": 0,
"subscription": null,
"sms_status": 0,
"url_status": 1,
"visited_count": 0,
"country_id": 11,
"created_id": 84,
"language": "en",
"expires_at": "2026-12-12",
"attachment": "",
"url": "http://demo.hesabe.com/s/977YY8Q9",
"spliturl": "http://merchant.hesbstaging.com/sp/SP977YY8Q9",
"created_at": "2025-10-07 14:32:35",
"updated_at": "2025-10-07 14:32:35",
"en_sms": "",
"ar_sms": "",
"customer": {
"name": "Mohammed",
"email": "test@gmail.com",
"phone_number": "96566666666"
},
"created_by_merchant": {
"id": 84,
"name": "test"
},
"products": [],
"transaction": null
},
{
"id": 14727,
"invoice_type": 6,
"invoice_sub_type": "1",
"token": "84175983675597391317",
"access_key": "953668Y9",
"split_access_key": "SP977YY8Q9",
"merchant_id": 84,
"reference_number": "88445604",
"amount": "150.000",
"service_charge": "0.000",
"payment_method": [
"1",
"2"
],
"discount": "0.000",
"description": "test",
"sms_response": "",
"invoice_status": null,
"subscription": null,
"sms_status": 0,
"url_status": 1,
"visited_count": null,
"country_id": 11,
"created_id": 84,
"language": "en",
"expires_at": "2026-12-12",
"attachment": "",
"url": "http://demo.hesabe.com/s/953668Y9",
"spliturl": "http://merchant.hesbstaging.com/sp/SP977YY8Q9",
"created_at": "2025-10-07 14:32:35",
"updated_at": "2025-10-07 14:32:35",
"en_sms": "",
"ar_sms": "",
"customer": {
"name": "Mohammed",
"email": "test@gmail.com",
"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"
}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
HeStallMent invoice
HeStallMent Invoice that allows customers to pay in multiple installments through supported payment methods. This endpoint includes customer details, total amount, installment configurations