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.

Apple Pay Direct Integration

Native checkout experience

Implement Apple Pay directly on your website without redirects. This premium integration provides a native Apple Pay experience that significantly increases conversion rates and delivers the seamless checkout experience customers expect

Implementation Steps

Enable Apple Pay Payment Gateway Service With Hesabe

Request Support Team To Enable Payment Gateway Service With Apple Pay

Contact Hesabe Merchant Support Team:support@hesabe.com

Verfiy your domain with Hesabe Payment Gateway

Request domain whitelisting and Apple verification setup

Contact Hesabe IT Team:itsupport@hesabe.com

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

[MerchantWebsite]/.well-known/apple-developer-merchantid-domain-association.txt

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

https://sandbox.hesabe.com/checkout
Checkout.php
$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.

FieldTypeDescriptionRequired
merchantCode
NumericAssigned by HesabeYes
amount
NumericAmount in currencyYes
currency
StringISO currency codeYes
responseUrl
AlphanumericRedirect URL on successYes
failureUrl
AlphanumericRedirect URL on failureYes
version
Alphanumeric3.0Yes
orderReferenceNumber
StringYour reference / order IDYes
paymentType
NumericRefer to the "List of apple pay payment types" section below for more informationYes
variable5
StringMerchant Domain Name as example.comYes

List of apple pay payment types

Below are the available apple pay payment method options supported by Hesabe

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

FieldTypeDescriptionRequired
name
StringCustomer NameOptional
mobile_number
Numeric (8)Customer Mobile Number ( Without country code )Optional
email
StringCustomer Email AddressOptional
webhookUrl
StringYour endpoint for receiving payment statusOptional
variable1
AlphanumericCustom user parameter which will be included in the response when it returnsOptional
variable2
AlphanumericCustom user parameter which will be included in the response when it returnsOptional
variable3
AlphanumericCustom user parameter which will be included in the response when it returnsOptional
variable4
AlphanumericCustom user parameter which will be included in the response when it returnsOptional

Encrypt the Payload

Encrypt the payload using our encryption library, then post the encrypted payload to Hesabe’s checkout endpoint

Checkout.php
$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.

Checkout.php
$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.

OptionUse it when
A. npm package @hesabe-pay/direct-apple-payYou 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.

https://developer.apple.com/design/human-interface-guidelines/apple-pay

Option A: npm package

Install the package, or load it from the CDN:

npm i @hesabe-pay/direct-apple-pay

Pass 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:

checkout.php
<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:

Checkout.php
$baseUrl =  "https://sandbox.hesabe.com"; // Sandbox Endpoint
$hesabetoken= $responseDataJson->response->data;
Checkout.php
<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:

checkout.html
<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

Email address:itsupport@hesabe.com

Ready to Launch

Launch Your Integration

Transform your checkout experience
Instant Payments
Reduce cart abandonment with seamless one-touch payments
Bank-Level Security
Built-in fraud protection and secure tokenization
Mobile Optimized
Perfect experience across all Apple devices

By implementing Apple Pay Direct Integration, you're providing customers with the premium checkout experience they expect, resulting in higher conversion rates and increased customer satisfaction.