Open invoice

To create open invoices instantly and deliver them via link or QR Code

POST
/api/v1/open-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

Two types of open invoices

TypesDescription
FixedThe customer can pay only the specified fixed amount (Eg: 100.000 KWD)
OpenThe customer can pay any amount within the configured minimum and maximum limits (Eg: Between Min 50.000 KWD - Max 100.000 KWD)

1. Fixed amount invoice

Field NameDescriptionRequired
merchantCodePass the merchant code provided by HesabeYes
titlePass the invoice titleYes
amountTypePass value "0" for fixed amount invoiceYes
fixAmountPass the invoice amountYes
descriptionPass the invoice descriptionOptional

Sample fixed amount payload details:

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

  {    "merchantCode": "842217", // Pass the merchant code provided by Hesabe    "title": "Test", // Invoice title    "amountType": "0", // "0" For fixed amount invoice    "fixAmount": "100.000", // fixed amount     "expiryDate": "2026-12-05",  // "YYYY-MM-DD"     "description": "testing open invoice" // Invoice description  }

2. Open amount invoice

Field NameDescriptionRequired
merchantCodePass the merchant code provided by HesabeYes
titlePass the invoice titleYes
amountTypePass value "1" for open amount invoiceYes
minAmountPass the minimum amountYes
maxAmountPass the maximum amountYes
descriptionPass the invoice descriptionOptional

Sample open amount payload details:

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

  {    "merchantCode": "842217", // Pass the merchant code provided by Hesabe    "title": "Test", // Invoice title    "amountType": "1", // "1" For open amount invoice    "minAmount": "100.000", // min amount     "maxAmount": "200.000", // max amount     "expiryDate": "2026-12-05", // "YYYY-MM-DD"     "description": "testing open invoice" // Invoice description  }

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    "title": "Test", // Invoice title    "amountType": "0", // "0" For fixed amount invoice    "fixAmount": "100.000", // fixed amount     "expiryDate": "2026-12-05",  // "YYYY-MM-DD"     "description": "testing open invoice" // Invoice description  }

Step 2: Convert JSON Object into Encrypted string and post to Hesabe

{  "data": "0e7898bd7464d0c402fe8a949d9cbf9bca3bfa9735d17cf962b1ac6b427e1138e4bc76d1a9b60a7e0fea6664dc7e4efd7608e61e2feff2e03840f4d1aa80a460581d237bf9556d7e146b1b67e5969d2b3d6de27742305f4fd1dfdc0ea71160bfe94eb7330004c2c59bc3839b27fe6b83da9aeaa28cac395f89965c4d505f3dfdd2656505796e3aa5ce010b6067a55675"}

Step 3: Receive encrypted response from Hesabe

{  "response": "60a8f6241932227b840a9f5e36987f4df645edae356a969d3dd7123d8946484a5f191ee59ebbb12400cf554113efa8c5a39fedefc32863f24c63fcdbebffc2357b4c304b0a417abaaab79c3a6a23d052baad4b1ad4b51eae77a930983664ce011595f65f93134e9d041a0619a93fbc555be4bc7534daefcd23f10111d78c94eedd05e48f68fa451a3d010869eefcdb624406c62b285fa54176abecdca322dcf9623cc1b7a6c1386a48aceaa66452497b29bcae240c1d922f0c5b9d8f5d8aaf28d8e961cbcb672bb90916751b6c66b390233fca49ae68f0c5dd7a56b7d85a42c5316b2e2a918bc2502064a1f948054431b426df498a07baea852eb56ee4704579d3e5123cf2e450b04f3fcf35b2854ecfeb8bd9e39548241f0d6db7934a17485936227eab22c58d7593d4dd135c25508c234d513852c3c71b2bf20dae7375c58ae4a64d4f6a8119168a78bd48dbcd1d9c2ce264c6a906de042367b541dbd9508896148e07f8c9f4d2d045ee547fb16c82cdfd4cdcba5453c6190c36d0aff20545aa098906a6bfe1ba3d06d4beb6c352f24740526356f0dca914480ff9df3a997015b289ab0403d48f8e3141027adbc4c71f66b355708add0fd90bf34f56a6146aa72a2f8af4ea16abcec560ae998b83596f28c4fe5347cbb28f8d8145d075795f50f125a3505bfe9c2b026c03ccefc07ac05fd50627d7577226ecd2728a46d0a1dcd6f968a72c6e23e98e80dd7be44a8688f556b16ed90330ec9faa1ebc3df55867694a67f0f28541ad0f1c19f7e0019379ee8527dcfec8b171a31fb46528550fa58b505e2fedef4c17024dcd43441cb0351a6f0e445494d2a606d3c62d8eabb1e50bca8cea4ae5b11327d01b19dba4f7d5c8bd4ee81142d2e03080ef744a8f2a"}

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

{  "status": true,  "message": "Open Invoice has been created successfully.",  "response": {    "id": 924,    "merchant_id": 84,    "title": "Test",    "reference_number": "84175991794397745669933",    "type": "0",    "description": "testing open invoice",    "fixed_amount": "100.000",    "min_amount": null,    "max_amount": null,    "paid_status": 0,    "status": null,    "created_by": 84,    "created_at": "2025-10-08 13:05:43",    "updated_at": "2025-10-08 13:05:43",    "expiry_date": "2026-12-05",    "url": "https://merchant.hesbstaging.com/open-invoice/checkout/84175991794397745669933",    "total_amount_customer_paid": "0.000",    "total_customer_tried_count": null,    "total_customer_paid_count": 0  }}

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": "0e7898bd7464d0c402fe8a949d9cbf9bca3bfa9735d17cf962b1ac6b427e1138e4bc76d1a9b60a7e0fea6664dc7e4efd7608e61e2feff2e03840f4d1aa80a460581d237bf9556d7e146b1b67e5969d2b3d6de27742305f4fd1dfdc0ea71160bfe94eb7330004c2c59bc3839b27fe6b83da9aeaa28cac395f89965c4d505f3dfdd2656505796e3aa5ce010b6067a55675"})fetch("https://merchantapisandbox.hesabe.com/api/v1/open-invoice", {  method: "POST",  headers: {    "Content-Type": "application/json",    "accessCode": "c333729b-d060-4b74-a49d-7686a8353481",    "Accept": "application/json"  },  body})
Example Response
{  "status": true,  "message": "Open Invoice has been created successfully.",  "response": {    "id": 924,    "merchant_id": 84,    "title": "Test",    "reference_number": "84175991794397745669933",    "type": "0",    "description": "testing open invoice",    "fixed_amount": "100.000",    "min_amount": null,    "max_amount": null,    "paid_status": 0,    "status": null,    "created_by": 84,    "created_at": "2025-10-08 13:05:43",    "updated_at": "2025-10-08 13:05:43",    "expiry_date": "2026-12-05",    "url": "https://merchant.hesbstaging.com/open-invoice/checkout/84175991794397745669933",    "total_amount_customer_paid": "0.000",    "total_customer_tried_count": null,    "total_customer_paid_count": 0  }}