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
Base URL
Sandbox Base URL
bearerAuthAuthorizationBearer <JWT>Pass access token obtained from login endpoint
accessCode*stringPass the merchant access code issued by Hesabe
Accept*stringapplication/json
Content-Type*stringapplication/json
application/json- body
data*stringConvert 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": "150.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-11-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 Name | Description | Required |
|---|---|---|
merchantCode | Pass the merchant code provided by Hesabe | Yes |
mobileNumber | Pass the customer mobile number ( mobileNumber field is mandatory only when the invoiceType is set to 1 ) | Yes ( For SMS Invoice Only ) |
customerName | Pass the customer name | Optional |
amount | Pass the invoice amount | Yes |
countryCode | Pass 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" - WhatsApp | 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 ๐ | Optional |
expiresAt | Pass invoice expiry date "YYYY-MM-DD" ( Defalut is 3 Days ) | Optional |
referenceNumber | Pass invoice reference number | Optional |
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 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 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" |
| Deema | "18" |
| Samsung Pay | "20" |
Step 2: Convert the JSON object into an encrypted string format and post to Hesabe
{ "data": "0e7898bd7464d0c402fe8a949d9cbf9b36e81fdd93ada05447ec483d9853a1a47b4d96436827b2d95b63116682b51bb870cc6c480069823fcccae3c5bf39f396a5e658c9367ccc67e024cce60b406a8c9aa7e0de9ef3a28be05766a4ee4524ad870d36c6e79036393f08259187d5adb3f7d704d849dfe39a7436861f39eb2329eda975864b474bf0591217f869050ff4bfa886adcf86090a5f30d3bd6ebe7f7d941f8295ad4d4f3efa70294190c98453b0495df938c9464436a4b76f77fe037e4c300b2fd9215f871e76ea4a22bc1b86ab91103bb00356062e7e4ddc45b32be1c1a9a3cb68b9c392fc6762a6514cc00eecc729c94ef40846cfe38f4cc8b564fba26061bd965fcd7928be0ea96d4646c57017f52279de342849e49810885ac6a13b0a40c16dd460d2f371215e5c167cfeeb66bb9482eacce8f068039d946b00779748c894d4838d2013789b87238f9f20f72bff2c5c9811dd2e6fbae0d9863696e43ce928f9b20940bb3ec71d1b89801152faebfcfd62a24328b2c58c95f8c3481c6b2364a72302beaa1013e783b2f8258831b19e10850e5795248a1bcf6d1c148c71c87cfa8b1718c0ad07c836d22fc55bc0bfd8e7255cd2a89425bf4095c24b08ab9ec5fd4c94f72940904dadfdcadb4cd8b5e23d2f7ddd36c70ace3eafb4ee8888ffa0f28f8615f7e0290bba2b9298fded5365738dd48a38405c8efa8d20975ed5cf972b8e73a26d35d6712b22f1c45308ad5ec080cb3fd07c80b7d773d56f46c08aed638ad6f5b8923a2193e1124f994d9b80980cb76aa872a0a3c7f26605e9cc4b4530ca8791f1f241b0496ebf024fea381961033f549e6d4e5ad621abc2748cd359902d0b6d8ded5a90eb2efb9ffb61a35e23d6bcb0fcb3073d49df4e5e8dd15aa284c46d2753f0adf0afe32956"}Step 3: Receive encrypted response from Hesabe:
{ "response": "60a8f6241932227b840a9f5e36987f4d894e5813e1ec714a9f1093832ea77937e62bab06bd7f6d1f6c96864648eb00dab19d8a3cf8fcbe02ca678f6459ffa0801f57243bec0a13f37136aae4a5519e582af9763088df7eb8829a0712fb8977467a9b76ad2758937c44c89ff97c8e33630a30a160bcf1558d50c3103e7c1f86140dbbfea3affb7d1f3082510e7cee387c7aec5c178fab8c2b072965450e8f8dfc2f88f19fdbe7cbc85687f7542ba3e7c72d21bd907fd8fe58307355fc1051dc83031cdf7d1148a1ca7c0f9dd57b7ce04fea6cbc14542cd4f5adf1c6a6abe349e1d47d8476ff29d8fd53e9abeaf6ba12562a2fcc72353d80c20282b3b19b8f04868686dc0eb2b51a4a6316c5caa17e97befa1de5d0c068d59c9aaf441b94d59d807089dbdee5f054657043f278b8669f2416fae114c3977622588568464be289002c1c9d42032bf395927613232a30826a65b78140a8a0c756e2b148155293de3a43615bdad7c4d6429a6d435ae22f2c8338363f21f98569213939ec1895dca8aed2484d140a8fa706a500db5b1ff23c9cac1c2ebd09c66f9595442a0674aa24e81ff1b256c30c42fc7a41c7a3583ad42824a76a2a79a7d3656fff05384c0eb3aeca5cc905bb6d8a9675357bf45eb6787b1528c5093308ac40cdd843b6f25d31181db4359276f929134986236a47188a65afc7aee39f0ba755033cbdec65b7036074adceede2fa9e661271d66b9c2dc7c5cfe119bd0480d26062e374e3ba8dab591ea5d1be5c65fc17258bb11a1992f9cb4b6396a293b5eb73dd9f71fefaadcac927c88afe9abf389334fdd01fdd9681b8cc5cb3ccd87c47dd6098087abd71d781e35e73abecad2d05f3fb2c6a9d664c7c71bbcff1a6e9ee4835dfec816c00170398a9ef4868f870b519407d4488c27c50cf21fd4685f24781180b4eefec09c9f45712400545dabaf4a06ddd015ff918454fbd15c01652eedf1f0b653db7c81d8491f1477520b031a0d0171e34e317d4d65798e2b29aa4ed09110f22eea45600ae85981b3a4d07566d28a92e028084e3ba45893417dae26f35b556d70a5caa6bf0bf9888c99e090376d1f0991f5b7af2fe82db717dd9349b4a38dfb8845d608aae9a518adf1d9c9206591be1b76cfaff34cf2c8b611f07e9f2e05baa35c5866e4abe943f073f6352f104c5693cefedb90833b77d99172f32f5979020677fbfccc58a9c21abd4ba0797d269595e546b77393a89b5de66507c690c38628274f6697eceede7678b55f783f9b273202403069368850cc210172c397c0acfe7fe08667ec9f86774a757eab6f75e431df9b200a88d795c5ba639d3eb975c1213db3cea1bbef481d12b435dd245213c61a96aa9b35146553bbd5cbe68b902d18ea7ae845c33d1a1f35cb679066d8c36b2cac3897b66e87d8b2c2c8173fff41c8182aa294ca24b0474064dc97a204f9d8de9bf298db2348a02e045685a61e45a4b87bb46adae80a05df58abb2b6f63cdcc0f5e8d51edc65fbc1811e765d0ecba7040131d4de313196a325aa3d7a3a0e31fa42f347dd9f32c31fc2e71fdbf5064176d5c1fb8a40f682197d558fd28f077378b322f6f1e8fc7793b724056b983bfda4cd35165929b50cfca2a44a7b208bbd50c8241ae0504f350c12f52996ea822694eca8ef0505aca084a030d6ce9e492aa5b4032f6fb5f583bdff08d215dedab106751b2ada5614873321d817a367cdf4b2f25cc2356a6164e2d47a352cdbfa40bb1d0ca025347ec9490356dc16959592b8edf85dafe574bb9ffee75e9c06b9cfdf09891606462bd2d69701ecdd8526ac0d2297fd743c564beafdda2ee1e232f558e9a2feed929d0e96534aaf50e048ad181b2f95fc3d3ac05d646121663b773111c5318bbf311088946a204491a526b70b241f5c0ac96c82d312a414b6e0b8c7893301e54b9ccbeae0203d3b71354455b7ce68d619d371dc7114a87e98b693b4f44190d1c17da51e86a079071c7855e6ae9817bd92b0c2c37c358d2df11f60f8db63eac82ce0abc85d0e870d8b4c6ef6df0b585f324098e04044313a8dd401dd2c64d2965f063c33052ec4bbd2e62f140b34ddc6ab6604c1e65d0f3e13bc0b194a6e2f5c5f20d1daa73dce58afd62d7e2604e3a2b73c2194c4cb5d54a9b1bc3e7c0971ccd5c9301c5d339ccf749f81dfeb3de07b4dbd04e953fb55fa34f9ad472eef17a2022f0b2616933075ce45d57c829a1ce7bc161793815363bbcc99363230a4677ba1d696758b21fb5f7261f29b60a28a273bb932a364dbd1d7c68734ace77ba1c9f56f38e94490c839c5ca44c4572d7018a668bb31bd512c2c9c7af75cc8aa111d717743b2b81c1836ea5804c710157f65ef0505c2950e20aa8ec612e02af90e2285dea2ed11cf5bfb565d5a8bf63753655bcc39d3f552759ed42dc84bb0896604a265074d4fe9c694915db464e350896737f7f97c05f1f48b00e12159f9e1d4bcd01b84fedda6ce0705415b0aed9d55d7d841640c7be178d2f39f2073e141ecd2589fc1b74d013b448c692fe134895d2200859cc91804b9d5b8d6541a5962ac81b"}Step 4: Decrypt the API response and view the JSON output
{ "status": true, "message": "Invoices processed successfully.", "response": [ { "id": 14736, "invoice_type": 7, "invoice_sub_type": 3, "token": "8417599096009484213", "access_key": "96W66QR9", "split_access_key": "SP96W66QR9", "merchant_id": "84", "reference_number": "8849404", "amount": "150.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/96W66QR9", "spliturl": "http://merchant.hesbstaging.com/sp/SP96W66QR9", "created_at": "2025-10-08 10:46:40", "updated_at": "2025-10-08 10:46:40", "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": 14737, "invoice_type": 7, "invoice_sub_type": "3", "token": "8417599096009374777914", "access_key": "977YYQQ9", "split_access_key": "SP96W66QR9", "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-11-12", "attachment": "", "url": "http://demo.hesabe.com/s/977YYQQ9", "spliturl": "http://merchant.hesbstaging.com/sp/SP96W66QR9", "created_at": "2025-10-08 10:46:40", "updated_at": "2025-10-08 10:46:40", "en_sms": "", "ar_sms": "", "customer": { "name": "Mohammed", "email": "test@gmail.com", "phone_number": "96566666666" }, "created_by_merchant": { "id": 84, "name": "test" }, "products": [], "transaction": null } ]}Details fetched successfully. Decrypt the server response to view the final result
application/json- response
status?booleanmessage?stringresponse?array<>const body = JSON.stringify({ "data": "0e7898bd7464d0c402fe8a949d9cbf9b36e81fdd93ada05447ec483d9853a1a47b4d96436827b2d95b63116682b51bb870cc6c480069823fcccae3c5bf39f396a5e658c9367ccc67e024cce60b406a8c9aa7e0de9ef3a28be05766a4ee4524ad870d36c6e79036393f08259187d5adb3f7d704d849dfe39a7436861f39eb2329eda975864b474bf0591217f869050ff4bfa886adcf86090a5f30d3bd6ebe7f7d941f8295ad4d4f3efa70294190c98453b0495df938c9464436a4b76f77fe037e4c300b2fd9215f871e76ea4a22bc1b86ab91103bb00356062e7e4ddc45b32be1c1a9a3cb68b9c392fc6762a6514cc00eecc729c94ef40846cfe38f4cc8b564fba26061bd965fcd7928be0ea96d4646c57017f52279de342849e49810885ac6a13b0a40c16dd460d2f371215e5c167cfeeb66bb9482eacce8f068039d946b00779748c894d4838d2013789b87238f9f20f72bff2c5c9811dd2e6fbae0d9863696e43ce928f9b20940bb3ec71d1b89801152faebfcfd62a24328b2c58c95f8c3481c6b2364a72302beaa1013e783b2f8258831b19e10850e5795248a1bcf6d1c148c71c87cfa8b1718c0ad07c836d22fc55bc0bfd8e7255cd2a89425bf4095c24b08ab9ec5fd4c94f72940904dadfdcadb4cd8b5e23d2f7ddd36c70ace3eafb4ee8888ffa0f28f8615f7e0290bba2b9298fded5365738dd48a38405c8efa8d20975ed5cf972b8e73a26d35d6712b22f1c45308ad5ec080cb3fd07c80b7d773d56f46c08aed638ad6f5b8923a2193e1124f994d9b80980cb76aa872a0a3c7f26605e9cc4b4530ca8791f1f241b0496ebf024fea381961033f549e6d4e5ad621abc2748cd359902d0b6d8ded5a90eb2efb9ffb61a35e23d6bcb0fcb3073d49df4e5e8dd15aa284c46d2753f0adf0afe32956"})fetch("https://merchantapisandbox.hesabe.com/api/v1/invoice/emi", { 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": 14736, "invoice_type": 7, "invoice_sub_type": 3, "token": "8417599096009484213", "access_key": "96W66QR9", "split_access_key": "SP96W66QR9", "merchant_id": "84", "reference_number": "8849404", "amount": "150.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/96W66QR9", "spliturl": "http://merchant.hesbstaging.com/sp/SP96W66QR9", "created_at": "2025-10-08 10:46:40", "updated_at": "2025-10-08 10:46:40", "en_sms": "", "ar_sms": "", "customer": { "name": "Mohammed", "email": "test@gmail.com", "phone_number": "96566666666" }, "created_by_merchant": { "id": 84, "name": "test" }, "products": [], "transaction": null } ]}