Initiate VERIFY Session
Create a zero-amount checkout session to save a card with full 3DS authentication
Header Parameters
accessCodestring
Pass the merchant access code issued by Hesabe
Content-Typestring
application/json
datastring
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",
"amount": "0.000",
"paymentType": 2,
"saveCard": true,
"customer_id": 4088,
"version": "3.0",
"currency": "KWD",
"responseUrl": "https://sandbox.hesabe.com/customer-response?id=842217",
"failureUrl": "https://sandbox.hesabe.com/customer-response?id=842217"
}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 |
amount | Must be exactly 0.000 — triggers the VERIFY flow | Yes |
currency | ISO currency code (e.g. KWD) | Yes |
paymentType | Must be 2 — specifies MPGS Direct Payment | Yes |
version | Must be 3.0 | Yes |
saveCard | Must be true together with amount=0 | Yes |
customer_id | Hesabe Customer ID — the saved card is attached to this customer | Yes |
responseUrl | Redirect URL after successful verification | Yes |
failureUrl | Redirect URL if verification or 3DS fails | Yes |
variable1–5 | Custom parameters returned as-is in the callback | Optional |
Step 2: Convert the JSON object into an encrypted string format and post to Hesabe
{
"data": "0e7898bd7464d0c402fe8a949d9cbf9b84c9ca6239b5e015bd42c0d4b30b12eee96b2572bd8ec1da23c789e4a768ade29d95078106db26dea1d6937808cb847cd8d1da957235a4af7bfe172199bf6f5d81cdd3aba6fb7a81cc32b56987c31119db296056ad95878204a6736d324751d3ffc2a2bf109696313fecebb1eddb280d1884c950d0565b442f5fc8c20e74dd2f741e000cdc56419458b20de988ef11f6228847fd93f7b93b1679cff5cc5ff29d3fe33e9ae86a0c03d259b6750774a89e3349e734be1c88df97462c5bd1a3cbd5589ccae14a2616ad7a1a73ea5a83d862cac14e435fd04cd5186aad365d4654ce2a98cc35f8a2b69be06adacae297d956ab1dff4f2084f09004ccdbb833bd32b9"
}Step 3: Receive encrypted response from Hesabe:
{
"response": "60a8f6241932227b840a9f5e36987f4d7bd72b2f40c5721be69e19f15ae1b1129c22835b679fe1cc66774eb1871de228a47f3be33c02598b3770fdb8e1cfa2e4b73833e3f002ad9a47c07ce177b08ba94dc3124750e9ca55c1a5da233ebcf5543a29ec50e777dd88d46a4f15ed324b7c2731173d78762beec76715accf9c442e383c61afb1191f3491477f50bd82992d38ce77ebaf4b4e0a55548c9d856581501e8190adb4c74b5051edd7698f5d13cd9382e16a07a0c2c7096883abf3e5e4db104bc61bba718692860618ffa8261627ea0a04f87ce65ce067652602c397502ac70997bbc9b6b4e509bc021e180b2ec7b99c4a05e82be0fbbf22161727a564c1b34f982a6414bed6d34209eab2085d3a30e6d6cc0000df1e92e463c6923a53639d77d4e8dbe29eca78166a2ccee3e8ddf44d79b830845199d0efeed093a9ab86"
}Step 4: Decrypt the callback response at your responseUrl
{
"status": true,
"code": 1,
"message": "Card Verified",
"response": {
"resultCode": "VERIFIED",
"amount": "0.000",
"currency": "KWD",
"paymentToken": "MERCH20250426abc123",
"paymentId": null,
"paidOn": "2025-04-26 14:32:01",
"orderReferenceNumber": "signup_flow",
"trackID": 1270310,
"transactionId": "MERCH20250426abc123_PAY",
"variable1": "signup_flow",
"customer": {
"Name": "Ahmed Al-Mansouri",
"Email": "ahmed@example.com",
"Mobile": "+96512345678",
"CardNumber": "512345xxxxxx0008",
"CardType": "MASTERCARD"
},
"cardId": 77
}
}Response Body
application/json
application/json
application/json
application/json
application/json
const body = JSON.stringify({ "data": "0e7898bd7464d0c402fe8a949d9cbf9b84c9ca6239b5e015bd42c0d4b30b12eee96b2572bd8ec1da23c789e4a768ade29d95078106db26dea1d6937808cb847cd8d1da957235a4af7bfe172199bf6f5d81cdd3aba6fb7a81cc32b56987c31119db296056ad95878204a6736d324751d3ffc2a2bf109696313fecebb1eddb280d1884c950d0565b442f5fc8c20e74dd2f741e000cdc56419458b20de988ef11f6228847fd93f7b93b1679cff5cc5ff29d3fe33e9ae86a0c03d259b6750774a89e3349e734be1c88df97462c5bd1a3cbd5589ccae14a2616ad7a1a73ea5a83d862cac14e435fd04cd5186aad365d4654ce2a98cc35f8a2b69be06adacae297d956ab1dff4f2084f09004ccdbb833bd32b9"})fetch("https://sandbox.hesabe.com/checkout", { method: "POST", headers: { "Content-Type": "application/json", "accessCode": "c333729b-d060-4b74-a49d-7686a8353481" }, body}){
"status": true,
"code": 1,
"message": "Card Verified",
"response": {
"resultCode": "VERIFIED",
"amount": "0.000",
"currency": "KWD",
"paymentToken": "MERCH20250426abc123",
"paymentId": null,
"paidOn": "2025-04-26 14:32:01",
"orderReferenceNumber": "signup_flow",
"trackID": 1270310,
"transactionId": "MERCH20250426abc123_PAY",
"variable1": "signup_flow",
"customer": {
"Name": "Ahmed Al-Mansouri",
"Email": "ahmed@example.com",
"Mobile": "+96512345678",
"CardNumber": "512345xxxxxx0008",
"CardType": "MASTERCARD"
},
"cardId": 77
}
}{
"status": false,
"message": "Invalid request data — please check your payload and try again",
"response": null
}{
"status": false,
"message": "Unauthorized — the provided accessCode is missing or invalid",
"response": null
}{
"status": false,
"message": "Forbidden — you do not have permission to access this resource",
"response": null
}{
"status": false,
"message": "Internal Server Error — an unexpected error occurred, please try again later",
"response": null
}