Initiate Checkout

Create a zero-amount checkout session to securely save the customer’s card with full 3DS authentication. For subsequent (first actual) transactions using the saved card, the checkout must be initiated with the actual payment amount, not a zero amount

Header Parameters

accessCodestring

Pass the merchant access code issued by Hesabe

Content-Typestring

application/json

Request Body

datastring

Convert 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", // Actual checkout amount — must be greater than zero
  "paymentType": 2, // '2' = MPGS Direct Payment
  "saveCard": true, // Pass `true` to show a "Save card" checkbox to the user
  "customer_id": 4088, // Hesabe Customer ID — the saved card is attached to this customer
  "version": "3.0",
  "currency": "KWD",
  "channel": "mobile", // 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>"
  }
}

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", // Must be exactly 0.000 — triggers the VERIFY flow
  "paymentType": 2, // '2' = MPGS Direct Payment
  "saveCard": true, // Must be `true` to initiate card save
  "customer_id": 4088, // Hesabe Customer ID — the card is attached to this customer
  "version": "3.0",
  "currency": "KWD",
  "channel": "mobile", // 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>"
  }
}

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

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

Response Body

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

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
}

Header Parameters

Request Body

Flow A — Checkout ( amount > 0 )

Step 1: Create the JSON payload

Step 2: Encrypt the payload and POST to Hesabe

Step 3: Receive the encrypted response from Hesabe

Step 4: Decrypt the response

Step 5: Navigation listener / Transaction result data

Step 6: Decrypt transaction result data

Flow B — Card Verification ( amount = 0.000 )

Step 1: Create the JSON payload

Step 2: Encrypt the payload and POST to Hesabe

Step 3: Receive the encrypted response from Hesabe

Step 4: Decrypt the response

Step 5: Navigation listener / Transaction result data

Step 6: Decrypt the response

Response Body

200application/json

400application/json

401application/json

403application/json

500application/json

Flow A — Checkout ( `amount > 0` )

Flow B — Card Verification ( `amount = 0.000` )

application/json

application/json

application/json

application/json

application/json