Laravel Tap Payment Gateway

Accept payments via Tap — KNET, Mada, Visa, Mastercard, Apple Pay, STC Pay, Tabby, Tamara, and more

Laravel package for integrating Tap Payments - the unified payment platform in the Middle East. Supports KNET, Mada, Visa, Mastercard, American Express, Apple Pay, Google Pay, STC Pay, Tabby, Tamara, Benefit, Fawry, OmanNet, NAPS, and more.

A professional Laravel package for integrating Tap Payments - the unified payment platform in the Middle East. Supports KNET, Mada, Visa, Mastercard, American Express, Apple Pay, Google Pay, STC Pay, Tabby, Tamara, Benefit, Fawry, OmanNet, NAPS, and more.

📋 Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Phase 1: Payment Processing (Charges)
• Phase 2: Order Management
• API Methods
• Webhook Handling
• Testing
• Security
• Integration Scenarios
• Countries & Currencies

Features

Phase 1 — Payment Processing

• ✅ Create Charge (hosted checkout page — src_all)
• ✅ Retrieve Charge (verify payment status)
• ✅ List Charges (with filters)
• ✅ Update Charge (metadata/description)
• ✅ Webhook receiver with hashstring validation
• ✅ Transaction logging (migration included)
• ✅ Sandbox & Production environments
• ✅ Multiple payment sources (cards, KNET, Mada, STC Pay, Apple Pay, etc.)

Phase 2 — Order Management

• ✅ Authorize (hold payment, auth-only)
• ✅ Capture (collect authorized payment)
• ✅ Void (cancel authorized payment)
• ✅ Refund (return funds)
• ✅ Token Management (create tokens)
• ✅ Customer Management (create/list)
• ✅ Saved Cards (list/delete)

Requirements

Installation

Publish Configuration

Publish & Run Migration (Optional but Recommended)

Configuration

Environment Variables

Add these to your .env file:

Service Provider & Facade

The package auto-discovers via Laravel's package discovery. If disabled, register manually:

🟢 Phase 1: Payment Processing (Charges)

Phase 1 covers the basic "Charge" flow — the most common integration. Customer is redirected to a Tap-hosted checkout page, pays, and returns to your app.

User Journey (Step by Step)

Routes Registered (Phase 1)

Quick Start — Phase 1 Only

Using the Provided Routes

The simplest integration. Route your users to the checkout form:

The customer will be redirected to the Tap hosted checkout page, then back to /tap/callback after payment.

Using the Facade Directly (Custom UI)

Handling Callback (tap/callback)

When the customer completes payment on Tap's page, they are redirected back to {redirect.url} with ?tap_id=chg_xxxxxxxx. Your callback handler should:

1. Get the tap_id from query string
2. Call Tap::getCharge(tap_id) to verify the status
3. Check if status is CAPTURED (success) or any other status
4. Update your order accordingly

🔵 Phase 2: Order Management

Phase 2 adds Authorize-Capture-Void-Refund flow plus token/customer management.

Additional routes:

Authorize → Capture Flow

Void Flow

Refund Flow

API Methods

Phase 1: Charges

Phase 2: Authorize & Order Management

Phase 2: Tokens, Customers & Saved Cards

Webhook Handling

Tap sends server-to-server POST notifications to your webhook URL after payment events.

Webhook Payload Example

Webhook Hashstring Validation

The package automatically validates the webhook signature. Here's how it works:

The hashstring is computed as:

Custom Webhook Handler

You can listen to the dispatched events:

Integration Scenarios

Scenario A: Phase 1 Only (Minimum Integration)

You want a simple hosted checkout. No authorize/capture/refund.

1. Add your .env variables
2. Add a POST form to route('tap.pay') with amount
3. Handle callback at route('tap.callback')
4. Done.

Scenario B: Phase 1 (your own) + Phase 2 (this package)

You already have a charge integration (either via this package, another package, or direct API calls). You want to add authorize/capture/void/refund:

1. Use Tap::createAuthorize() for auth-only payments
2. Use Tap::captureCharge() to capture
3. Use Tap::voidCharge() to void
4. Use Tap::refundCharge() to refund
5. Webhook automatically logs all events

Scenario C: Full Integration (Phase 1 + Phase 2)

All features enabled. This is the recommended approach for production.

Set up your webhook URL in your Tap Dashboard:

Routes Reference

Customising Routes

Publish the config and modify the routes section:

Webhook Events

The package dispatches these events:

Payment Sources

The source.id field determines which payment methods appear:

For a tokenized card, pass the token ID as source:

Countries & Currencies

Security

Credential Safety

• NEVER hardcode TAP_SECRET_KEY in your code — use .env only
• Secret keys start with sk_ — keep them server-side only
• Public keys start with pk_ — safe to use in frontend
• The package never logs full secret keys (masked as sk_****)

Webhook Validation

All webhooks are validated using HMAC-SHA256 hashstring verification. If the hash doesn't match, the webhook is rejected with HTTP 403.

Safe Logging

• ✅ API requests logged without sensitive data
• ✅ Transaction IDs logged for debugging
• ✅ Error responses logged with message only
• ❌ Secret keys never logged
• ❌ Card numbers never logged

Testing

Run Package Tests

The test suite covers:

• Unit\TapClientTest: URL resolution, method existence
• Unit\WebhookValidatorTest: Hashstring generation, validation, currency rounding
• Feature\TapChargeControllerTest: Route accessibility

Sandbox Credentials

Set these in your .env for sandbox testing:

Note: Your API keys are provided by Tap Payments through the merchant dashboard. You can retrieve them from the Merchant Dashboard → Developers → API Keys. The keys cannot be generated or modified by the developer; they are assigned by Tap.

For viewing reports and payment transactions (both staging and production), visit: Tap Reports Portal

Test Cards — Local Payment Methods

KNET Page: Select KNET Test Card [KNET1] from the Bank drop-down.

Test Cards — Credit / Debit Cards

Expiry Date — Response Mapping

Use these expiry dates to simulate specific outcomes:

CSC / CVV — Response Mapping

STC Pay — Test Phone Numbers

Changelog

See CHANGELOG for recent changes.

Security

If you discover security issues, please email [email protected] instead of using the issue tracker.

License

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

Support

• Issues: GitHub Issues
• Tap API Docs: https://developers.tap.company
• Author: AL-AGHBARI Fatehi ([email protected])