Split invoice

Create a split invoice so that the payment can be collected in separate installments or by different payers

POST
/api/v1/invoice/split

Base URL

Sandbox Base URL

Strictly for sandbox testing. Never use the sandbox URL in your production environment.
https://merchantapisandbox.hesabe.com

Authorization

bearerAuth
headerAuthorizationBearer <JWT>

Pass access token obtained from login endpoint

Header Parameters

accessCode*string

Pass the merchant access code issued by Hesabe

Accept*string

application/json

Content-Type*string

application/json

Request Body

application/json
  1. body
data*string

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             "language" : "en", // "en" for english , "ar" for arabic            "description": "test",            "customerName": "Mohammed",            "mobileNumber": "66666666",             "countryCode": "965",          },          {            "amount": "150.000",            "expiresAt": "2026-12-12",            "referenceNumber": "88445604",            "merchantCode" :"842217",            "invoiceType": "1" , // Invoice type "1" for SMS invoice and "0" for URL sharing             "language" : "en", // "en" for english , "ar" for arabic            "description": "test",            "customerName": "Mohammed",            "mobileNumber": "66666666",             "countryCode": "965"          }      ]    }

Payload Details

Contains the list of parameters and their corresponding values required to make the API request.

Field NameDescriptionRequired
merchantCodePass the merchant code provided by HesabeYes
mobileNumberPass the customer mobile number ( mobileNumber field is mandatory only when the invoiceType is set to 1 )Yes ( For SMS Invoice Only )
customerNamePass the customer nameOptional
amountPass the invoice amountYes
countryCodePass the mobile number country code ( countryCode field is mandatory only when the invoiceType is set to 1 )Yes ( For SMS Invoice Only )
invoiceType"0" - URL sharing, "1" - SMS, "6" - WhatsAppYes
allocatePayTypePass 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 ๐Ÿ‘‡Optional
expiresAtPass invoice expiry date "YYYY-MM-DD" ( Defalut is 3 Days )Optional
referenceNumberPass invoice reference numberOptional
customerEmailPass customer email addressOptional
languageDefalut is "en" and for arabic invoices "ar"Optional
descriptionPass invoice description detailsOptional
itemsListPass product details as a JSON-encoded string of an array of objects. A plain JSON array is rejected with 422 "The items list must be a valid JSON string". 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  }]

Send it JSON-encoded as a string (for example JSON.stringify(items) / json_encode($items)):

"itemsList": "[{\"itemTitle\":\"Iphone\",\"rate\":\"120.000\",\"quantity\":\"1\",\"amount\":\"120.000\"},{\"itemTitle\":\"Iphone 13\",\"rate\":\"160.000\",\"quantity\":\"1\",\"amount\":\"160.000\"}]"

List of payment types

Note: Default subscribed payment method will be displayed if you are not passing allocatePayType

Payment Method TypesValue
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"
Deema"18"
Samsung Pay"20"

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

Details fetched successfully. Decrypt the server response to view the final result

application/json
  1. response
status?boolean
message?string
response?array<>
Example Request
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})
Example Response
{  "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    }  ]}