Download the PHP package amzad/apple-pay-knet without Composer

amzad/apple-pay-knet

Apple Pay on the Web + KNET Direct integration for Laravel.
Designed for Kuwaiti merchants who want to accept Apple Pay payments through the KNET payment gateway with minimal setup.

Table of Contents

1. Requirements
2. Installation
3. Apple Pay Setup
4. Configuration
5. Database Migration
6. Publishing Assets
7. Environment Variables
8. Frontend Integration
9. Handling the Callback
10. Using the Facade
11. API Endpoints
12. Transaction Model
13. Exception Handling
14. Sandbox vs Production
15. Troubleshooting

Requirements

• PHP ^7.4 or ^8.0
• Laravel ^8.0 | ^9.0 | ^10.0 | ^11.0 | ^12.0
• PHP extensions: curl, openssl, json
• An Apple Developer account with Apple Pay enabled
• An Apple Pay Merchant Identity Certificate (.pem)
• A KNET merchant account with API credentials
• Your site must be served over HTTPS with a registered Apple Pay domain

Installation

Step 1 — Install the package via Composer

Step 2 — Auto-discovery (Laravel 8+)

Laravel will automatically register the service provider and facade via package auto-discovery. No manual registration is required.

If you have disabled auto-discovery, add the following to your config/app.php:

Apple Pay Setup

Before any code runs, you must complete the Apple Pay merchant setup. These steps are required and must be done in order.

Step 1 — Enroll in the Apple Developer Program

Go to developer.apple.com and ensure you have an active paid developer account.

Step 2 — Create a Merchant ID

1. In the Apple Developer portal, go to Certificates, Identifiers & Profiles → Identifiers.
2. Click + and select Merchant IDs.
3. Enter a description and identifier (e.g. merchant.com.yourstore).
4. Click Register.

Step 3 — Register your domain

1. In the Apple Developer portal, open your Merchant ID.
2. Under Apple Pay on the Web, click Add Domain.
3. Download the domain verification file Apple provides.

4. Place it at this exact path on your server:

5. Click Verify in the developer portal.

The file must be accessible without redirect or authentication.

Step 4 — Create a Merchant Identity Certificate

1. In the Apple Developer portal, open your Merchant ID.
2. Under Merchant Identity Certificate, click Create Certificate.

3. Generate a CSR (Certificate Signing Request) on your server:

4. Upload the .csr file to Apple and download the resulting .cer file.

Step 5 — Convert the certificate to PEM format

Apple issues .cer files in DER format. Convert it:

Step 6 — Store certificates securely

• Store merchant.pem and merchant.key outside your web root (e.g. /etc/ssl/apple-pay/).
• Set restrictive permissions:

Configuration

Step 1 — Publish the config file

This creates config/apple-pay-knet.php.

Step 2 — Review the config file

Database Migration

Step 1 — Publish the migration

Step 2 — Run the migration

This creates the apple_pay_transactions table with the following columns:

Skip this step if you set 'log_transactions' => false in your config.

Publishing Assets

Publish the JavaScript handler

This copies apple-pay-handler.js to public/vendor/apple-pay-knet/js/. The Blade component references it automatically.

Publish the Blade views (optional)

This copies the views to resources/views/vendor/apple-pay-knet/ so you can customise them.

Environment Variables

Add the following to your .env file:

Replace KNET_ENDPOINT with the production URL when going live (provided by your bank).

Frontend Integration

Option A — Blade Component (Recommended)

Step 1 — Publish the JS asset

Step 2 — Add the component to your Blade view

The component automatically:

• Loads the Apple Pay SDK and the apple-pay-handler.js script (once per page)
• Shows/hides the button based on device support
• Handles merchant validation and payment processing

Available Component Props

Custom JS Callbacks Example

Option B — Manual JavaScript Integration

If you prefer not to use the Blade component, include the scripts manually and initialise ApplePayKnet directly.

Step 1 — Include the scripts

Step 2 — Add the Apple Pay button element

Step 3 — Initialise the handler

Full init options

Handling the Callback

After a successful payment, the package auto-submits a hidden form that POSTs the KNET response fields to your callbackUrl. Create a route and controller action to handle this:

Step 1 — Define the route

Step 2 — Handle the callback

Important: Always verify the result field equals "CAPTURED" before marking an order as paid. Do not rely solely on the callback being called.

Using the Facade

You can charge directly from your own controller without going through the package's HTTP endpoints:

charge() method signature

API Endpoints

The package registers the following routes automatically under the configured route_prefix (default: apple-pay):

POST /apple-pay/process-payment

Request body:

Success response:

Error response:

Changing the route prefix

This changes the routes to /payments/apple/validate-merchant and /payments/apple/process-payment.

Adding custom middleware

Transaction Model

When log_transactions is enabled, you can query the Transaction model directly:

Available scopes

Transaction statuses

Exception Handling

The package throws two exception types:

ApplePayException

Thrown when Apple merchant validation fails.

KnetException

Thrown when KNET authorization fails or a network error occurs.

Sandbox vs Production

Sandbox (testing)

Use the KNET test endpoint:

Apple Pay requires a real device with a real card even in sandbox mode. Safari on Mac with a linked iPhone/Apple Watch will work.

Production

Replace with your bank-provided production endpoint:

Also update APPLE_PAY_VALIDATION_URL if Apple provides a different production URL:

Troubleshooting

Apple Pay button not showing

• Ensure the page is served over HTTPS.
• Ensure you are using Safari on a compatible Apple device.
• Verify the domain is registered and verified in the Apple Developer portal.
• Check browser console for [ApplePayKnet] log messages.

Merchant validation returns 400

• Confirm your certificate is in PEM format (not DER). Run:

• Verify your domain is registered in the Apple Developer portal under the correct Merchant ID.
• Make sure the .well-known/apple-developer-merchantid-domain-association file is publicly accessible.
• Check the certificate has not expired.

Certificate errors on boot

The package validates your certificate on every merchant validation call. Common errors and their fixes:

KNET returns no trackid

• Verify KNET_ID and KNET_PASSWORD are correct.
• Ensure KNET_RESPONSE_URL and KNET_ERROR_URL are publicly accessible HTTPS URLs.
• Check you are using the correct endpoint (sandbox vs production).

CSRF token mismatch

• Ensure csrfToken is passed in the JS init config.
• The Blade component handles this automatically via {{ csrf_token() }}.
• If using the API from a SPA, include the X-CSRF-TOKEN header or use a Sanctum token.

License

This package is open-sourced software licensed under the MIT license.

Author

Amzad — [email protected]