README

Laravel package for integrating with the Paymera eGate payment gateway API.

Requirements

• PHP ^8.1
• Laravel ^10.0 | ^11.0 | ^12.0

Installation

composer require amjad-gh/paymera-payment-laravel

The service provider and facade are auto-discovered by Laravel.

Publish the config file

php artisan vendor:publish --tag=paymera-config

Configuration

Add the following variables to your .env file:

PAYMERA_BASE_URL=https://egate-t.paymera.cc   # test environment
# PAYMERA_BASE_URL=https://egate.paymera.cc   # production environment

PAYMERA_USERNAME=your-username
PAYMERA_PASSWORD=your-password
PAYMERA_TERMINAL_ID=your-terminal-id
PAYMERA_LANG=en

Security: credentials are sent via HTTP Basic Auth on the server side only and are never exposed to the client.

The published config file (config/paymera.php) contains:

return [
    'base_url'    => env('PAYMERA_BASE_URL', 'https://egate-t.paymera.cc'),
    'username'    => env('PAYMERA_USERNAME'),
    'password'    => env('PAYMERA_PASSWORD'),
    'terminal_id' => env('PAYMERA_TERMINAL_ID'),
    'lang'        => env('PAYMERA_LANG', 'en'),
];

Usage

Create a Payment

use Casper\Paymera\Facades\Paymera;
use Casper\Paymera\DTOs\CreatePaymentRequest;

$result = Paymera::createPayment(new CreatePaymentRequest(
    amount:      5000,                                             // amount in smallest currency unit
    callbackURL: 'https://yourapp.com/orders/1234/payment/return', // see note below
    triggerURL:  'https://yourapp.com/payment/webhook',            // server-to-server notification
    terminalId:  config('paymera.terminal_id'),
    lang:        config('paymera.lang'),
    notes:       'Order #1234',                                    // optional
));

// $result->paymentId  — unique payment identifier
// $result->redirectUrl — redirect the user here to complete payment

return redirect($result->redirectUrl);

callbackURL is the URL the gateway redirects the user to when they click Cancel or Close after the payment flow. Include the merchant order identifier in the URL so your landing page can identify which order is returning (e.g. /orders/1234/payment/return).

Get Payment Status

use Casper\Paymera\Facades\Paymera;

$status = Paymera::getPaymentStatus($paymentId);

if ($status->isAccepted()) {
    // payment succeeded
}

if ($status->isPending()) {
    // still waiting
}

if ($status->isFailed()) {
    // payment failed
}

if ($status->isCanceled()) {
    // payment was canceled
}

// Raw enum value:  $status->status  (PaymentStatus enum)
// Other fields:    $status->rrn, $status->amount, $status->terminalId,
//                  $status->creationTimestamp, $status->notes

Cancel a Payment

use Casper\Paymera\Facades\Paymera;

Paymera::cancelPayment($paymentId);

API Environments

Switch environments by changing PAYMERA_BASE_URL in your .env.

DTOs

CreatePaymentRequest

CreatePaymentResult

PaymentStatusResult

PaymentStatus Enum

use Casper\Paymera\Enums\PaymentStatus;

PaymentStatus::Pending  // 'P'
PaymentStatus::Accepted // 'A'
PaymentStatus::Failed   // 'F'
PaymentStatus::Canceled // 'C'

Exception Handling

All exceptions extend PaymeraException which extends RuntimeException.

use Casper\Paymera\Exceptions\PaymeraException;
use Casper\Paymera\Exceptions\UnauthorizedException;
use Casper\Paymera\Exceptions\PaymentFailedException;

try {
    $result = Paymera::createPayment($request);
} catch (UnauthorizedException $e) {
    // Invalid credentials — error code 1
} catch (PaymentFailedException $e) {
    // Payment failed — error code 100
} catch (PaymeraException $e) {
    // Any other Paymera error
    $e->getErrorCode();  // raw error code from API
    $e->getMessage();    // error message from API
}

Testing

The package ships with a Pest test suite. From the package root:

composer install
./vendor/bin/pest tests/

In your own application tests, use Http::fake() to mock the gateway:

use Illuminate\Support\Facades\Http;

Http::fake([
    '*/api/create-payment' => Http::response([
        'ErrorCode'    => 0,
        'ErrorMessage' => 'Success',
        'Data'         => [
            'paymentId' => 'pay_test123',
            'url'       => 'https://egate-t.paymera.cc/pay/pay_test123',
        ],
    ]),
]);

License

MIT