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.

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", // 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 NameDescriptionRequired
merchantCodePass the merchant code provided by HesabeYes
mobileNumberPass the customer mobile number ( mobileNumber field is mandatory only when the invoiceType is set to 1 )Yes ( For SMS Invoice Only )
customerNamePass the customer nameOptional
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
allocatePayTypePass 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
expiresAtPass invoice expiry date "YYYY-MM-DD" ( Defalut is 3 Days )Optional
referenceNumberPass invoice reference numberOptional
customerEmailPass customer email addressOptional
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\"}]"

List of payment types

Note: Default subscribed payment method will be displayed if you are not passing allocatePayType

Payment Method TypesValue
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    }  }}

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": "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})
Example Response
{  "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  }}