Download the PHP package darshphpdev/laravel-edfapay without Composer

Laravel EdfaPay

A fluent, modern Laravel wrapper for the EdfaPay v2.0 REST API engine. Effortlessly initiate secure hosted payments and capture transactional callbacks using a clean builder pattern and an decoupled, event-driven webhook architecture.

For full API insights, please review the official EdfaPay API Documentation Guide.

✨ Features

• 🏎️ Modern Authentication: Fully optimized for the modern X-API-KEY header system.
• 🌊 Fluent Payment Builder: Chainable setters ensure clean, error-free transaction payloads.
• ⚡ Environment Toggle: Seamless runtime switching between demo and live servers.
• 🔔 Decoupled Webhooks: Automatic stream-parsing fallback that broadcasts standard Laravel events.
• ⚙️ Configurable Paths: Fully customize or completely disable default package webhook routing.
• 🪓 Cross-Version Stability: Native Guzzle abstraction ensures stability across various Laravel installations.

📋 Requirements

• 🐘 PHP 7.4 | 8.0 | 8.1 | 8.2 | 8.3
• ⚡ Laravel 8.0 | 9.0 | 10.0 | 11.0 | 12.0 | 13.0

📥 Installation

You can pull the package into your project via composer:

🔧 Setup

Publish the vendor configuration file to your application's config directory:

Add your operational keys to your application's environment file (.env):

⚙️ Configuration

The published configuration maps out as follows under config/edfapay.php:

🩺 Verifying Your Setup

After configuration, run the following command to validate your credentials and confirm API connectivity:

A successful output looks like:

If EDFAPAY_API_KEY is missing, the package will throw a RuntimeException on first use to prevent silent failures in production.

📖 Usage

🚀 Initiating a Payment Intent

Leverage the EdfaPay Facade and its fluent chain builders to spin up an absolute transaction payload. Per the EdfaPay Webhook Docs, you can set your notification capture endpoint dynamically per-transaction using setNotificationUrl() or rely on your global merchant dashboard webhook configurations.

⚠️ Validation & Error Handling

Calling initiate() automatically validates the payload before dispatching the request. The following fields are required: orderId, currency, amount, customerDetails.name, customerDetails.email, customerDetails.phone, successUrl, and failureUrl.

Use the package's typed exceptions to handle failures cleanly:

Sample edfaapay successful response:

🔍 Querying a Transaction Status

Use queryTransaction() to fetch the current status of any transaction by its ID. Useful for reconciliation jobs or when a webhook is missed.

💸 Initiating a Refund

Use the initRefund() fluent builder to refund a previously approved transaction. transactionId and amount are required. reason is optional.

🔔 Handling Webhook Notifications (IPN)

This package automatically captures postback webhook stream payloads under the route defined in your configuration file, writes production metrics, and converts them into a standard decoupled event payload.

1. Register a Listener

Map your custom listener to the package event inside your application's App\Providers\EventServiceProvider array matrix:

2. Write the Database Sync Logic

Inside your listener, fetch the verified data payload seamlessly to run your model syncs:

🛡️ Security

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

👨‍💻 Credits

• Mustafa Ahmed

📄 License

This package is open-source software licensed under the MIT License.