Direct Apple Pay
This comprehensive guide will help you integrate your application or platform with Hesabe's Payment Gateway API, supporting multiple integration methods and advanced features.
Implementation Steps
Enable Apple Pay Payment Gateway Service With Hesabe
Request Support Team To Enable Payment Gateway Service With Apple Pay
Verfiy your domain with Hesabe Payment Gateway
Request domain whitelisting and Apple verification setup
Once whitelisted, Hesabe will provide an Apple Domain Verification File
This file needs to be added on your website’s hosting server in the following path:
Domain Verification File Path
Create a Checkout Request
Send the encrypted data to Hesabe's checkout API endpoint with proper headers including the access code.
Pre-requisites Setup
You can follow the Checkout Setup guide to get started.
Hesabe Request Handler
You can follow the Hesabe Request Handler guide to get started.
NPM Package Available
A lightweight, framework-agnostic javaScript library for apple pay integration through the Hesabe payment gateway, works with React, Vue, Angular, or vanilla JavaScript.
Please refere npm package details here Hesabe Apple Pay Direct
Sandbox Checkout API
Below Checkout API strictly for sandbox testing only. Never use these sandbox URL's in production environment
$baseUrl = "https://sandbox.hesabe.com";
$CheckoutApiUrl = "{$baseUrl}/checkout";
$requestData = [
"merchantCode" => "842217",
"amount" => "2",
"paymentType" => "9", // Refer to the "List of apple pay payment types" section below for more information
"responseUrl" => "https://sandbox.hesabe.com/customer-response?id=842217",
"failureUrl" => "https://sandbox.hesabe.com/customer-response?id=842217",
"version" => "3.0",
"orderReferenceNumber" => "9874659805",
"currency" => "KWD",
"name" => "customername",
"email" => "customeremail@gmail.com",
"mobile_number" => "66666666",
"variable1" => "First__variable",
"variable2" => "Second__variable",
"variable3" => "Third__variable",
"variable4" => "forth__variable",
"variable5" => "example.com",
"webhookUrl" => 'https://yourdomain.com/example'
];
Read more about Hesabe Webhook URL
You can follow the Hesabe Webhook Request guide to get started.
| Field | Type | Description | Required |
|---|---|---|---|
merchantCode | Numeric | Assigned by Hesabe | Yes |
amount | Numeric | Amount in currency | Yes |
currency | String | ISO currency code | Yes |
responseUrl | Alphanumeric | Redirect URL on success | Yes |
failureUrl | Alphanumeric | Redirect URL on failure | Yes |
version | Alphanumeric | 3.0 | Yes |
orderReferenceNumber | String | Your reference / order ID | Yes |
paymentType | Numeric | Refer to the "List of apple pay payment types" section below for more information | Yes |
variable5 | String | Merchant Domain Name as example.com | Yes |
List of apple pay payment types
Below are the available apple pay payment method options supported by Hesabe
| Payment Types | Value |
|---|---|
| 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" |
Additional Checkout API Parameters
Optional parameters that allow you to include extra data or customize the checkout flow in your API request
| Field | Type | Description | Required |
|---|---|---|---|
name | String | Customer Name | Optional |
mobile_number | Numeric (8) | Customer Mobile Number ( Without country code ) | Optional |
email | String | Customer Email Address | Optional |
webhookUrl | String | Your endpoint for receiving payment status | Optional |
variable1 | Alphanumeric | Custom user parameter which will be included in the response when it returns | Optional |
variable2 | Alphanumeric | Custom user parameter which will be included in the response when it returns | Optional |
variable3 | Alphanumeric | Custom user parameter which will be included in the response when it returns | Optional |
variable4 | Alphanumeric | Custom user parameter which will be included in the response when it returns | Optional |
Encrypt the Payload
Encrypt the payload using our encryption library, then post the encrypted payload to Hesabe’s checkout endpoint
$encryptedData = HesabeCrypt::encrypt($requestData, $encryptionKey, $ivKey);
$checkoutRequestData = new Request([
'data' => $encryptedData
]);
$checkoutRequest = Request::create($CheckoutApiUrl, 'POST', $checkoutRequestData->all());
$checkoutRequest->headers->set('accessCode', $accessCode);Decrypt the Response
Decrypt the response returned from the checkout request using the same encryption library used for encryption during the request.
$checkoutResponse = Route::dispatch($checkoutRequest);
$checkoutResponseContent = $checkoutResponse->content();
$decryptedResponse = HesabeCrypt::decrypt($checkoutResponseContent, $encryptionKey, $ivKey);
$responseDataJson = json_decode($decryptedResponse);Choose how to show Apple Pay
Use the decrypted response.data from the checkout response with one of the two options below.
| Option | Use it when |
|---|---|
A. npm package @hesabe-pay/direct-apple-pay | You build the page with React, Vue, Angular or your own JavaScript and want your own button and callbacks |
B. Hosted script /applepay?data=… | You render the page on the server (for example PHP) and want Hesabe's script to drive the button |
Apple Pay Design Guidelines
Style your button following Apple's guidelines. The button is only shown and usable on Apple Pay-capable devices, so handle that case in your page.
Option A: npm package
Install the package, or load it from the CDN:
npm i @hesabe-pay/direct-apple-payPass the decrypted response.data as requestData, call init() once the page is ready, and call processPayment() with the same paymentType you sent to checkout when the customer clicks your button:
<script src="https://unpkg.com/@hesabe-pay/direct-apple-pay@latest/cdn/hesabe-apple-pay.min.js"></script>
<button id="apple-pay-btn" onclick="handleApplePayClick()">
Pay with Apple Pay
</button>
<script>
const applePay = new HesabeApplePay({
requestData: '<?= $hesabetoken ?>', // decrypted response.data from checkout
env: 'sandbox', // or 'production'
paymentAttemptedCallback: (result) => console.log('Payment result:', result),
paymentCancelledCallback: () => console.log('Payment cancelled'),
});
applePay.init();
function handleApplePayClick() {
applePay.processPayment(9); // the paymentType used in checkout, e.g. 9 = MPGS Apple Pay
}
</script>Full usage, including React and Vue examples, is in the package documentation.
Option B: Hosted script
Load Apple's SDK and Hesabe's script with the decrypted response.data:
$baseUrl = "https://sandbox.hesabe.com"; // Sandbox Endpoint
$hesabetoken= $responseDataJson->response->data;<script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>
<script src="{$baseUrl}/applepay?data={$hesabetoken}"></script>The script looks for an element with the id applePayment and the class applePaybtn, and handles the click itself, so don't add your own onclick:
<div id="applePayment">
<button type="button" class="applePaybtn">Pay with Apple Pay</button>
</div>Domain validation
The hosted script currently validates the Apple Pay session against Hesabe's domain rather than the domain you pass in variable5. If Apple Pay doesn't start on your domain, use Option A, or contact Hesabe IT support.
Apple Pay setup completed!
Test on an Apple Pay-capable device before going live.
For Any Technical Assistance
If you encounter any issues or need support during setup or integration, please contact our technical team for assistance.
Hesabe IT Support
Ready to Launch
In-Direct Payment Method
Customers are redirected to Hesabe's secure payment gateway landing page where they can select their preferred payment method. This method offers quick implementation with automatic security handling.
Saved Card Payments
Direct Payments & Saved Cards (Embedded) allow users to complete payments directly within your app or website without redirection, ensuring a seamless checkout experience. It also enables secure storage of card details via tokenization, allowing faster and convenient repeat transactions.
