Initiate a VERIFY session
POST
Base URL
Sandbox Base URL
Strictly for sandbox testing. Never use the sandbox URL in your production environment.
https://sandbox.hesabe.com
Create a VERIFY checkout session with amount=0 and saveCard=true. The customer authenticates their card via 3DS — no charge is made. On completion, Hesabe redirects to your responseUrl with an encrypted data parameter containing the cardId.
accessCode*stringPass the merchant access code issued by Hesabe
Content-Type*stringapplication/json
application/json- body
data*stringConvert payload JSON object to encrypted string and send it to the server
Flow A — Checkout ( amount > 0 )
Use this flow to initiate a real payment. The customer completes the payment inside a WebView.
Step 1: Create the JSON payload
{ "merchantCode": "842217", "amount": "3.000", // [!code ++] Actual checkout amount — must be greater than zero "paymentType": 2, // [!code ++] '2' = MPGS Direct Payment "saveCard": true, // [!code ++] Pass `true` to show a "Save card" checkbox to the user "customer_id": 4088, // [!code ++] Hesabe Customer ID — the saved card is attached to this customer "version": "3.0", "currency": "KWD", "channel": "mobile", // [!code ++] Pass `mobile` to receive a `webviewUrl` in the response "responseUrl": "https://sandbox.hesabe.com/customer-response?id=842217", "failureUrl": "https://sandbox.hesabe.com/customer-response?id=842217"}| Field Name | Description | Required |
|---|---|---|
merchantCode | Merchant code provided by Hesabe | Yes |
amount | Checkout amount — must be greater than 0 | 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 | Pass true to display a "Save card" checkbox; omit or false to hide it | Optional |
channel | Pass mobile to receive a webviewUrl in the response | Yes |
customer_id | Hesabe Customer ID — required if saveCard is true | Conditional |
responseUrl | Redirect URL after successful payment | Yes |
failureUrl | Redirect URL if payment or 3DS fails | Yes |
variable1–5 | Custom parameters returned as-is in the callback | Optional |
Step 2: Encrypt the payload and POST to Hesabe
{ "data": "0e7898bd7464d0c402fe8a949d9cbf9b84c9ca6239b5e015bd42c0d4b30b12eee96b2572bd8ec1da23c789e4a768ade29d95078106db26dea1d6937808cb847cd8d1da957235a4af7bfe172199bf6f5d81cdd3aba6fb7a81cc32b56987c31119db296056ad95878204a6736d324751d3ffc2a2bf109696313fecebb1eddb280d1884c950d0565b442f5fc8c20e74dd2f741e000cdc56419458b20de988ef11f6228847fd93f7b93b1679cff5cc5ff29d3fe33e9ae86a0c03d259b6750774a89e3349e734be1c88df97462c5bd1a3cbd5589ccae14a2616ad7a1a73ea5a83d862cac14e435fd04cd5186aad365d4654ce2a98cc35f8a2b69be06adacae297d956ab1dff4f2084f09004ccdbb833bd32b9"}Step 3: Receive the encrypted response from Hesabe
{ "response": "60a8f6241932227b840a9f5e36987f4d7bd72b2f40c5721be69e19f15ae1b1129c22835b679fe1cc66774eb1871de228a47f3be33c02598b3770fdb8e1cfa2e4b73833e3f002ad9a47c07ce177b08ba94dc3124750e9ca55c1a5da233ebcf5543a29ec50e777dd88d46a4f15ed324b7c2731173d78762beec76715accf9c442e383c61afb1191f3491477f50bd82992d38ce77ebaf4b4e0a55548c9d856581501e8190adb4c74b5051edd7698f5d13cd9382e16a07a0c2c7096883abf3e5e4db104bc61bba718692860618ffa8261627ea0a04f87ce65ce067652602c397502ac70997bbc9b6b4e509bc021e180b2ec7b99c4a05e82be0fbbf22161727a564c1b34f982a6414bed6d34209eab2085d3a30e6d6cc0000df1e92e463c6923a53639d77d4e8dbe29eca78166a2ccee3e8ddf44d79b830845199d0efeed093a9ab86"}Step 4: Decrypt the response
{ "status": true, "response": { "data": "<encrypted_payload>", "webviewUrl": "https://sandbox.hesabe.com/pay/webview?data=<encrypted_payload>" // [!code highlight] }}| Field | Description |
|---|---|
status | true on success |
response.data | Encrypted payload — decrypt again to get full order details |
response.webviewUrl | Open this URL in a WebView for the customer to complete 3DS/payment |
Step 5: Navigation listener / Transaction result data
Listen your navigation state change (responseUrl / failureUrl) and get the decrypted result data from that URL
const onNavigationStateChange = (navState) => { const url = navState.url; if (url && url.includes('https://sandbox.hesabe.com/customer-response?id=842217')) { closeWebView(); // close the web view page const parts = url.split('data='); // get the decrypted result data form the `responseUrl` or `failureUrl` if (parts[1]) { navigation.navigate('TransactionResult', { resultdata: parts[1]. // Navigate to result page with transaction data }); } } };Step 6: Decrypt transaction result data
Decrypt the data from the responseUrl or failureUrl to get the transaction results
Flow B — Card Verification ( amount = 0.000 )
Use this flow to verify and save a card without charging the customer. On completion you receive a cardId to use with the Recurring Payment API.
Step 1: Create the JSON payload
{ "merchantCode": "842217", "amount": "0.000", // [!code ++] Must be exactly 0.000 — triggers the VERIFY flow "paymentType": 2, // [!code ++] '2' = MPGS Direct Payment "saveCard": true, // [!code ++] Must be `true` to initiate card save "customer_id": 4088, // [!code ++] Hesabe Customer ID — the card is attached to this customer "version": "3.0", "currency": "KWD", "channel": "mobile", // [!code ++] Pass `mobile` to receive a `webviewUrl` in the response "responseUrl": "https://sandbox.hesabe.com/customer-response?id=842217", "failureUrl": "https://sandbox.hesabe.com/customer-response?id=842217"}| Field Name | Description | Required |
|---|---|---|
merchantCode | 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 — required to initiate card verification | Yes |
channel | Pass mobile to receive a webviewUrl in the response | Yes |
customer_id | Hesabe Customer ID — the verified 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: Encrypt the payload and POST to Hesabe
{ "data": "0e7898bd7464d0c402fe8a949d9cbf9b84c9ca6239b5e015bd42c0d4b30b12eee96b2572bd8ec1da23c789e4a768ade29d95078106db26dea1d6937808cb847cd8d1da957235a4af7bfe172199bf6f5d81cdd3aba6fb7a81cc32b56987c31119db296056ad95878204a6736d324751d3ffc2a2bf109696313fecebb1eddb280d1884c950d0565b442f5fc8c20e74dd2f741e000cdc56419458b20de988ef11f6228847fd93f7b93b1679cff5cc5ff29d3fe33e9ae86a0c03d259b6750774a89e3349e734be1c88df97462c5bd1a3cbd5589ccae14a2616ad7a1a73ea5a83d862cac14e435fd04cd5186aad365d4654ce2a98cc35f8a2b69be06adacae297d956ab1dff4f2084f09004ccdbb833bd32b9"}Step 3: Receive the encrypted response from Hesabe
{ "response": "60a8f6241932227b840a9f5e36987f4d7bd72b2f40c5721be69e19f15ae1b1129c22835b679fe1cc66774eb1871de228a47f3be33c02598b3770fdb8e1cfa2e4b73833e3f002ad9a47c07ce177b08ba94dc3124750e9ca55c1a5da233ebcf5543a29ec50e777dd88d46a4f15ed324b7c2731173d78762beec76715accf9c442e383c61afb1191f3491477f50bd82992d38ce77ebaf4b4e0a55548c9d856581501e8190adb4c74b5051edd7698f5d13cd9382e16a07a0c2c7096883abf3e5e4db104bc61bba718692860618ffa8261627ea0a04f87ce65ce067652602c397502ac70997bbc9b6b4e509bc021e180b2ec7b99c4a05e82be0fbbf22161727a564c1b34f982a6414bed6d34209eab2085d3a30e6d6cc0000df1e92e463c6923a53639d77d4e8dbe29eca78166a2ccee3e8ddf44d79b830845199d0efeed093a9ab86"}Step 4: Decrypt the response
{ "status": true, "response": { "data": "<encrypted_payload>", "webviewUrl": "https://sandbox.hesabe.com/pay/webview?data=<encrypted_payload>" // [!code highlight] }}| Field | Description |
|---|---|
status | true on success |
response.data | Encrypted payload — decrypt again to get full order details |
response.webviewUrl | Open this URL in a WebView for the customer to complete 3DS/payment |
Step 5: Navigation listener / Transaction result data
Listen your navigation state change (responseUrl / failureUrl) and get the decrypted result data from that URL
const onNavigationStateChange = (navState) => { const url = navState.url; if (url && url.includes('https://sandbox.hesabe.com/customer-response?id=842217')) { closeWebView(); // close the web view page const parts = url.split('data='); // get the decrypted result data form the `responseUrl` or `failureUrl` if (parts[1]) { navigation.navigate('TransactionResult', { resultdata: parts[1]. // Navigate to result page with transaction data }); } } };Step 6: Decrypt the response
{ "status": true, "code": 1, "message": "Card Verified", "response": { "resultCode": "VERIFIED", // [!code highlight] "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", // [!code highlight] "CardType": "MASTERCARD" // [!code highlight] }, "cardId": 77 // [!code highlight] }}| Field | Description |
|---|---|
code | 1 — card successfully verified |
message | Human-readable status ("Card Verified") |
response.resultCode | "VERIFIED" — card passed 3DS authentication |
response.customer.CardNumber | Masked card number for display |
response.customer.CardType | Card scheme (e.g. MASTERCARD, VISA) |
response.cardId | Store this — used as the token for Recurring Payment API calls |
VERIFY session created — customer is redirected to complete card authentication
application/json- response
status?booleancode?integermessage?stringresponse?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})Example Response
{ "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 }}