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

POST
/api/v1/invoice/

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", // Pass the merchant code provided by Hesabe        "mobileNumber":"66666666",        "customerName": "TEST",        "customerEmail": "test@gmail.com",        "referenceNumber": "1234",        "amount": "80.000", // Pass three decimal value        "countryCode": "965", // Mobile number country code        "invoiceType": "0" , // Invoice type "1" for  "SMS" and "0" for URL        "description": "Invoice testing",        "subscription": "1", // "0" for Quick invoice , "1" for subscription invoice        "expiresAt": "2026-12-12", // invoice expiry date        "frequency": "1", // Monthly        "noofRecurrence": "1", //  No of recurrances        "SubscriptionType" : "1", // subscription Type - "1" - On Demand" , "0" - "Auto Payments"        "allocatePayType": "15", // Required for subscription invoices: "15" or "19"        "startDate": "2025-02-12", // subscription start date        "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 NameDescriptionRequired
merchantCodePass the merchant code provided by HesabeYes
mobileNumberPass the customer mobile numberYes
customerNamePass the customer nameYes
customerEmailPass the customer email addressYes
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
expiresAtPass invoice expiry date "YYYY-MM-DD" ( Defalut is 3 Days )Optional
referenceNumberPass invoice reference numberOptional
subscriptionPass "1" for subscription invoiceYes
frequencyPass "1" for monthly subscriptionYes
noofRecurrencePass the value to capture number of times. Eg: "1" time in a monthYes
SubscriptionType"0" for "ON Demand", merchant needs to capture through API "1" for "auto payments", Hesabe will capture based the date & number of recurrenceYes
allocatePayTypePayment type of the subscription. Only "15" or "19" are accepted; the request is refused with 422 "The allocate pay type field is required" without itYes
languageDefalut is "en" and for arabic invoices "ar"Optional
descriptionPass invoice description detailsOptional
webhookPass your webhook URLOptional
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\"}]"

Step 2: Convert the JSON object into an encrypted string format and post to Hesabe

{  "data": "0e7898bd7464d0c402fe8a949d9cbf9b64a98634a092ee6261f9f3d288eb01a442a32ba890f3e1db57ebd53c63045f936f182ae1c3cbec0508f473bb7f3b24bf941a5f2b665796cf68b949adb85b9d0f6ae5d0f37bd93608089b5f2a5b46df71fbf8945071bb4e23e6e863549db0d6151ec894086e8e4580e67eedb2c3aa137bd0bfef133ca86e6043123d96e184edd970597243df61c6c7799b30b49fd15d6bbe7dde24c60fac68129ceacc6b258a178c27e9589b5e2ca52d276081a0afb576b59857a94a18adcb6f7835d793b29bc2c32e2dd3adaa47c242404c56a6cbd83d4e27b534bedbda1d4854e299136ced154875b83295061d8e23f95350e56c43226013876ec27e9d2681a7751834c9d52a1ef1473a1601289cc3ccb3a2bfe7d75ac94bf4f42b5611ce010f6de37ff8654f83927a68b47a7fee192d69dcc41413c76e78c841efe436f52089529139c4fd4a99df0d8e2c980c4ea8694e8beacc0c4643aa6da1ea0734653afa3189d819ddeb"}

Step 3: Receive encrypted response from Hesabe:

{  "response": "60a8f6241932227b840a9f5e36987f4d894e5813e1ec714a9f1093832ea77937e6611102e7fb85a9c6b25a3c5fdf4ef16077ffcdcbfd043049cde6c2bcca3061965b341c00323db25f7ac1ad9505ae8d9e1ecf3734f146376ca4e302c4cfcf47905a28b343372798a6ad62264283b0b66f3d47537bcd8922737a1c0b890e4fe79b9c5e91385d39f63c76460677cbdda1a1281f13b26a51d1237737b12302e54fe0f8988afab743ad0c1cea9cb9b63fe4e8e1388b5354057b54e9cf7247c6516484797c90476d99aae8ac7e33583608a589c53e04e15969706dd3944ed74960d3bf517207e209f51a50a4e690415181a98803b781bd648d9bad5e7eeaab6ea683593f034f10a37bbdbf3217d4142510723cd85cc331c975e9b3e0807567711fd0523ed65f119f16928d2776aa727e038d02ff192a2025737769793c3e3a9da270d8de0047bb4ebb71e3863af337dc8f9ea9dfd751ed5720123bbf991fa9d03e806ecbcd6f4b710b8305fd1f5a0715f411ddab6698fdbd4a4e683eda7a7612edab7f003d25b5d5490bf5ae736246ea55a73d7f09487ef1ad5c21f6611a47300b96baf5c5b2f5db146da2bbcb69d212a7af371208957ef2587c2ce8abd079322b0a26f832deac044367aac77b322e72cd47e2c7fb44a6cc58d539170abb5bf5178d35704a33f5a95cf26a5b6e7f8bf74d172807c1bf6717bf76d8290d527d92baa50d324ab4a61b32fd47a18e087ac16fa7df1d8183a54ff274ef55dad074ead3b6eb23050549c4c60e33ea721f0b2a992acfd3784b8c40e627ea81400697dc873737bbb8e1e0c1b75355a6d914dcc7aa4a9477bb48a558e5e000d9988702738b56fefa7205d2940cde5ac889f405e6024f2219208ad6346f1b59422de5ba1704a144747831ba081567d1fb542e7a93e01e909daace27e516088d83a896d85b1a6d5d97eabc5083170381bdbe31550b3c955a9a654b219878fea315f122fc41b1864d5ebd942a05bd9734c28bcb24e350aa60c0fb38dca1c1e176511a5763b28b899a1937404cf3a89aee429ed17b69045930a77ed309e76565cd72330fa348ca1a54f695cf6a7a4d06bc588e7f6273c96bce92481072c2881a82d43114164398117b3b0be1bc0068b75ac74b0c0ed8e6dcfb93faef6006c4ca2c4da6ae312903b2cf6f4f937a8778550860996b9d251b396d92a799813591aeef94818b8543efdae308774c7d5aa173777f9dfa1355104cc1c7c68cb57b3560b6ff9e2074f5668b61b2d75abad3b2fbb7006093ca17e075951e8570ba20507521017ebe07e50f0e514f3583bce1e0e79cf3738c73e64b557e514263f7b147c4be456423036766172c21689918ab97adc7dbf80c4e92e0583471f31f3be2f98711427e44a6de5a2663ce3060aee0cb27d5e1b6330074ea4389e23d8b58800c3b002228ea127dd0cb070f59cef11231218ddabf5de77613e389b5c7d77fedb5d87dfaca90e2f00fad55dec9f4b1f099949cdacf9118136d9679639c3ac4724da75d4e91d1d874c00033cab3c68fe55874e395fbb286f90c9f920155cb5cb3cd80a1d008ebab908296cda9547860dfc9b584421092a847a9af62683e2ed3895fa4b8fb55733f284b257a5e8bb68dbe63a3bb173fbfd399768ae1c37b476e5ded0c51e4b458418fc587abf92c60a20ae742b44aa894c66d46f755ed589f9a958e16265de932854008598dd7efa189fc2f376aa4bbd13fc9fd8e5406876f90112536411416fa6422a71dd0748394190c6f44f5528e59b4899b89a8378b004c33092411fe220348e36e1b20749b8a037e62a0630f293daaf7d54ed4d14d627ac005a950e3379a5c932303a03b8f297e312d6dfb132e00439c5ae5c2169fe6749eb76e525e2b7d541cf0180674bcaafde80dfe533a16fd07a111ddbaa8cecb4dae5807050dfbb8158a3bc947717973ac6e4b727373503711ee0a77a0d79d5ddc79616855176022aca3db8f3c2f4676263bda39e860d6c72c91e5eeaed749de6a0e99fe380a5f13ad4877d53e5bbf7648f1617d1296e59a5e620ec348436b6745d578df34366b4834b1b3d156f12bcd4460542296a7590238dc4cc5f3ba68f41a1cdf527fc9d18b342d0345c98c5d69b770718f8c26a3ed7f10769b3241a77ea004f38367a966f855190da06ab1c7a58a3775248c199027c267cd3b3ef03abd966a5ea53fe3a96443b01084e78424007b3a1199dfbbde319f3e685421c9c8d692ce2d9c89091b9fc74add9066d21766eb24bff3b388f321e7596bbd048d011ecb0f68bd72857aca1a766ec3"}

Step 4: Decrypt the API response and view the JSON output

{  "status":true,  "message":"Invoice generated successfully",  "response":{      "id":14714,      "invoice_type":1,      "invoice_sub_type":"3",      "token":"84175982518093871998",      "access_key":"96W66ER9",      "split_access_key":"",      "merchant_id":84,      "reference_number":"1234",      "amount":0,      "service_charge":"0.000",      "payment_method":[        "15"      ],      "discount":"0.000",      "description":"Invoice testing",      "sms_response":"",      "invoice_status":null,      "subscription":{        "id":609,        "customer_phone":"66666666",        "customer_email":"",        "payment_type_id":15,        "service_type_id":2,        "amount":80,        "reference_number":"84175982518093871998",        "frequency":"Monthly",        "status":3,        "start_date":"2025-02-12 12:00:00",        "number_of_installments":1,        "next_billing_date":"2025-02-12 12:00:00",        "type":1,        "created_at":"2025-10-07 11:19:40",        "updated_at":"2025-10-07 11:19:40"      },      "sms_status":0,      "url_status":1,      "visited_count":null,      "country_id":11,      "created_id":84,      "language":"ar",      "expires_at":"2026-12-12",      "attachment":"",      "url":"http://demo.hesabe.com/s/96W66ER9",      "spliturl":null,      "created_at":"2025-10-07 11:19:40",      "updated_at":"2025-10-07 11:19:40",      "en_sms":"Hi TEST , \r\nYour transaction amount is KD 0 with the ref no : 1234 . Review and pay at",      "ar_sms":"hi TEST,\r\nمبلغ الصفقة هو دينار كويتي 0 مع المرجع رقم: 1234. مراجعة وتدفع في",      "customer":{        "name":"TEST",        "email":"",        "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?
Example Request
const body = JSON.stringify({  "data": "0e7898bd7464d0c402fe8a949d9cbf9b64a98634a092ee6261f9f3d288eb01a442a32ba890f3e1db57ebd53c63045f936f182ae1c3cbec0508f473bb7f3b24bf941a5f2b665796cf68b949adb85b9d0f6ae5d0f37bd93608089b5f2a5b46df71fbf8945071bb4e23e6e863549db0d6151ec894086e8e4580e67eedb2c3aa137bd0bfef133ca86e6043123d96e184edd970597243df61c6c7799b30b49fd15d6bbe7dde24c60fac68129ceacc6b258a178c27e9589b5e2ca52d276081a0afb576b59857a94a18adcb6f7835d793b29bc2c32e2dd3adaa47c242404c56a6cbd83d4e27b534bedbda1d4854e299136ced154875b83295061d8e23f95350e56c43226013876ec27e9d2681a7751834c9d52a1ef1473a1601289cc3ccb3a2bfe7d75ac94bf4f42b5611ce010f6de37ff8654f83927a68b47a7fee192d69dcc41413c76e78c841efe436f52089529139c4fd4a99df0d8e2c980c4ea8694e8beacc0c4643aa6da1ea0734653afa3189d819ddeb"})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})
Example Response
{  "status": true,  "message": "Invoice generated successfully",  "response": {    "id": 14714,    "invoice_type": 1,    "invoice_sub_type": "3",    "token": "84175982518093871998",    "access_key": "96W66ER9",    "split_access_key": "",    "merchant_id": 84,    "reference_number": "1234",    "amount": 0,    "service_charge": "0.000",    "payment_method": [      "15"    ],    "discount": "0.000",    "description": "Invoice testing",    "sms_response": "",    "invoice_status": null,    "subscription": {      "id": 609,      "customer_phone": "66666666",      "customer_email": "",      "payment_type_id": 15,      "service_type_id": 2,      "amount": 80,      "reference_number": "84175982518093871998",      "frequency": "Monthly",      "status": 3,      "start_date": "2025-02-12 12:00:00",      "number_of_installments": 1,      "next_billing_date": "2025-02-12 12:00:00",      "type": 1,      "created_at": "2025-10-07 11:19:40",      "updated_at": "2025-10-07 11:19:40"    },    "sms_status": 0,    "url_status": 1,    "visited_count": null,    "country_id": 11,    "created_id": 84,    "language": "ar",    "expires_at": "2026-12-12",    "attachment": "",    "url": "http://demo.hesabe.com/s/96W66ER9",    "spliturl": null,    "created_at": "2025-10-07 11:19:40",    "updated_at": "2025-10-07 11:19:40",    "en_sms": "Hi TEST , Your transaction amount is KD 0 with the ref no : 1234 . Review and pay at",    "ar_sms": "hi TEST, مبلغ الصفقة هو دينار كويتي 0 مع المرجع رقم: 1234. مراجعة وتدفع في",    "customer": {      "name": "TEST",      "email": "",      "phone_number": "96566666666"    },    "created_by_merchant": {      "id": 84,      "name": "test"    },    "products": [],    "transaction": null  }}