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.
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", // 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, "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 |
webhook | Pass your webhook URL | 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": 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 } }}Details fetched successfully. Decrypt the server response to view the final result
application/json- response
status?booleanmessage?stringresponse?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 }}