Single invoice
Creates a new invoice for the merchant with customer details, 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", // Customer mobile number
"customerName": "TEST",
"referenceNumber": "12349899", // Invoice number
"amount": "20.000", // Pass three decimal value
"countryCode": "965", // Mobile number country code
"invoiceType": "1" , // Invoice type "1" for SMS invoice and "0" for URL sharing
"description": "Invoice testing", // Invoice description
"expiresAt":"2025-12-12",
"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 ( 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 invoice | 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 |
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 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" |
Step 2: Convert the JSON object into an encrypted string format and post to Hesabe
{
"data": 0e7898bd7464d0c402fe8a949d9cbf9b64a98634a092ee6261f9f3d288eb01a442a32ba890f3e1db57ebd53c63045f936f182ae1c3cbec0508f473bb7f3b24bf941a5f2b665796cf68b949adb85b9d0f6ae5d0f37bd93608089b5f2a5b46df71e00b21fccd73635896bc78dca763a78de47a7cb0cb1cd63734945fbb33d1b037d7e526c7ff952fd44313994f9a49ffec6d4555d682da65a2a71672750615fe4d9bbfdb038e900518878a14c76eba7f3d5c0dc6ec62072f10e2ac1125a6fd595fbd0a77bbd05608c1e39a86dee7b763321d8a7192b7ebbc595a4c3dcde757f766428344079e630ec3f6510373ff5d41a1c3983500f0b1d1869c6c0e0aee97fc0343c29331e1f6db06ee6ffbc22988359b888ff01cba4442d8f67283d5cbce7c7653687a546c3a2cdcd603496777f478e5
}Step 3: Receive encrypted response from Hesabe:
{
"response": "60a8f6241932227b840a9f5e36987f4d894e5813e1ec714a9f1093832ea77937e6611102e7fb85a9c6b25a3c5fdf4ef16077ffcdcbfd043049cde6c2bcca306189ab575493ceedb6b52fecf8a8f177a57649670bb7f6f49625577484cdbd51743ac8ee30e49f2549750e0d512e5951f8695925eab882b5d60acfefdbdd538ec0f98c7c1e338af53071fa0c365066937089dce0bea00086f9821ba1f20df7dde64d0519a41d1c800319e5fc7d5de0d9ffd8dcddbd7f62c517b2328afabd579368300bb5b44357986b458163b8be95ebf15a9626c34bc4c435497cd738abb16156b950dfe5586abd6db3fe0861be1f365d904115d61bc4088534a3aea43c16f801d6bcf6f086e5ca9ce23a62251d4ec3c54235b286b781e81ed46feef36c7e7625156064000e03b809cabb57d0b93306d05d34028727447f9c21b455df7a0f26f0d703c3f15cf464e3cb7a17b54b70c32eeb99d95c469830358616f8dc0c96daadc3465f6cf7ef8dcc7de8d1b698cd5246cf25a4fc232c8ddef3f2ebb26801e8543568a3f71c7c6a87143750627f7e8f5d5beac65ccff5b1166fa41676eb4b7897d8db86d2296870018ba35177e3d1fddec8dda3df28efcb81209a6b0b00357ef4e32a8cd5e8c95ded76b50266faaa5b6f7942275e70dda82007eca6700ee924e49c4eb654eb1f1f0f303edabd58b62cb78e07f8718ce8bea765fa24a98d4fc855a5e8a9c46f2fd63dc6afbd52cc5812604971ea90276c3efd1e95ea6475504ea416d35253f7faf2cc628ba20af506237c5a1a70106a00bf9685d9d2a444ebf6799f386cc4ce71b916f89c98945e1576aa70c4e822a9aa0923f373d46201fb877934269484161c1d679dd3f5da7db6132b8d70e0bfcf254c0d216203e746417a649617752d56505c8a39191f921497de96f755d02ebd0499493f501297c93c76814feefcf662f2217fd2cb765adc7cc303f0d7c6dbb18e096c409bf334216bf1dd5301f8f7f857a0cc144830c50851c909191abf649e538b44489e8e824527695831f2d2c512ac72394479762f87df3edb1678d178b0b60fb7fbef8c86abad7c19f28adc5d465cfd05a6d70f7f8214706731148a87d2f5c20a813a1a71bcb0247cd8db966cfca48a990ce9dd5c66109692ac2dc4a8ac93c8861d8553c0a19c95e173b2101a7f2bb0ac1ed008131869185a1c0e4dc381780c2f05a9e2f2334732b70d9005294e617c745f2965fab39fd118a801073589db11fe89a77db386d6ecfa31bb8d37559f2445e19b406012e973bc81a217808cb7b84dd255bd8bf6806104db7db905f5ae998df5ebb5ba04ac0c04bf4f85b414c2c653cea82067987ce0fcc83b7ceeeb3634fcfb28fd499bdd84e9c9df3ba667ac67223fb1dd402e043fc340bac438486cd664c03c2d728512d3d3ba8217dbc6082f4d9da980205cb2aa6287ae0f79d32b2421fdd49b7efe28b1ee146772824155d8944192be413905233b0d5decfbf48bc2da5c20cc4c5c42518af956dedd720a58295ea116082bf53d0337149e9b6e89cbca6d67993c8fd3ebfd7b2eec6cc927b56e53545bf33873b30ceb7df783a4360a23b0770045dad2f72e1157c90e1a839dbe66c62ad2c3454e9ab50cc3638a1446dcea88decd39cff73d479b7a7ecda047ad936864f9b0ff8ed389e0e7e063b8e894829bdd2d1259f9a16f43645c7cbec4351ce16845998d20d54bcc2e6cc21666996b7a55a8389ae86da9574c7a992fcd2ea3624934ad7273ab339a215223083397ab2fefba4893d95b69f73b656c88be2f70952fe349f5ed43d960918754f9258a0aba96dad03cc479d62893c8fe506dac781a0862850d5376"
}Step 4: Decrypt the api response and view the JSON output
{
{
"status": true,
"message": "Invoice generated successfully",
"response": {
"id": 14685,
"invoice_type": 1,
"invoice_sub_type": "3",
"token": "8417596519189744686058",
"access_key": "98WRR6R9",
"split_access_key": "",
"merchant_id": 84,
"reference_number": "12349899",
"amount": "20.000",
"service_charge": "0.000",
"payment_method": [
"1",
"2"
],
"discount": "0.000",
"description": "Invoice testing",
"sms_response": "",
"invoice_status": null,
"subscription": null,
"sms_status": 0,
"url_status": null,
"visited_count": null,
"country_id": 11,
"created_id": 84,
"language": "ar",
"expires_at": "2025-12-12",
"attachment": "",
"url": "http://demo.hesabe.com/s/98WRR6R9",
"spliturl": null,
"created_at": "2025-10-05 11:11:58",
"updated_at": "2025-10-05 11:11:58",
"en_sms": "Hi TEST , Your transaction amount is KD 20.000 with the ref no : 12349899 . Review and pay at",
"ar_sms": "hi TEST, مبلغ الصفقة هو دينار كويتي 20.000 مع المرجع رقم: 12349899. مراجعة وتدفع في",
"customer": {
"name": "TEST",
"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
application/json
const body = JSON.stringify({ "data": "0e7898bd7464d0c402fe8a949d9cbf9b64a98634a092ee6261f9f3d288eb01a442a32ba890f3e1db57ebd53c63045f936f182ae1c3cbec0508f473bb7f3b24bf941a5f2b665796cf68b949adb85b9d0f6ae5d0f37bd93608089b5f2a5b46df71e00b21fccd73635896bc78dca763a78de47a7cb0cb1cd63734945fbb33d1b037d7e526c7ff952fd44313994f9a49ffec6d4555d682da65a2a71672750615fe4d9bbfdb038e900518878a14c76eba7f3d5c0dc6ec62072f10e2ac1125a6fd595fbd0a77bbd05608c1e39a86dee7b763321d8a7192b7ebbc595a4c3dcde757f766428344079e630ec3f6510373ff5d41a1c3983500f0b1d1869c6c0e0aee97fc0343c29331e1f6db06ee6ffbc22988359b888ff01cba4442d8f67283d5cbce7c7653687a546c3a2cdcd603496777f478e5"})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": 14685,
"invoice_type": 1,
"invoice_sub_type": "3",
"token": "8417596519189744686058",
"access_key": "98WRR6R9",
"split_access_key": "",
"merchant_id": 84,
"reference_number": "12349899",
"amount": "20.000",
"service_charge": "0.000",
"payment_method": [
"1",
"2"
],
"discount": "0.000",
"description": "Invoice testing",
"sms_response": "",
"invoice_status": null,
"subscription": null,
"sms_status": 0,
"url_status": null,
"visited_count": null,
"country_id": 11,
"created_id": 84,
"language": "ar",
"expires_at": "2025-12-12",
"attachment": "",
"url": "http://demo.hesabe.com/s/98WRR6R9",
"spliturl": null,
"created_at": "2025-10-05 11:11:58",
"updated_at": "2025-10-05 11:11:58",
"en_sms": "Hi TEST , Your transaction amount is KD 20.000 with the ref no : 12349899 . Review and pay at",
"ar_sms": "hi TEST, مبلغ الصفقة هو دينار كويتي 20.000 مع المرجع رقم: 12349899. مراجعة وتدفع في",
"customer": {
"name": "TEST",
"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"
}{
"status": false,
"code": 506,
"message": "Invalid Request Data",
"response": null
}