Open invoice

Authorization

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

Request Body

datastring

Convert payload JSON object to encrypted string and send it to the server

Two types of open invoices

Types	Description
Fixed	The customer can pay only the specified fixed amount (Eg: 100.000 KWD)
Open	The 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 Name	Description	Required
`merchantCode`	Pass the merchant code provided by Hesabe	Yes
`title`	Pass the invoice title	Yes
`amountType`	Pass value "0" for fixed amount invoice	Yes
`fixAmount`	Pass the invoice amount	Yes
`description`	Pass the invoice description	Optional

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 Name	Description	Required
`merchantCode`	Pass the merchant code provided by Hesabe	Yes
`title`	Pass the invoice title	Yes
`amountType`	Pass value "1" for open amount invoice	Yes
`minAmount`	Pass the minimum amount	Yes
`maxAmount`	Pass the maximum amount	Yes
`description`	Pass the invoice description	Optional

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

application/json

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
})

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})

{
  "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
  }
}

{
  "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
}

Authorization

Header Parameters

Request Body

Two types of open invoices

1. Fixed amount invoice

Sample fixed amount payload details:

2. Open amount invoice

Sample open amount payload details:

Sample Encryption and Decryption Process:

Step 1: Create JSON Object

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

Step 3: Receive encrypted response from Hesabe

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

Response Body

200application/json

404application/json

500application/json

506application/json

application/json

application/json

application/json

application/json