PHP code example of epay-et / php-sdk

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

epay-et / php-sdk example snippets

use Epay\Epay;

$epay = new Epay(['api_key' => getenv('EPAY_SECRET_KEY')]);

$session = $epay->payments->initialize([
    'amount' => '250.00',
    'currencyCode' => 'ETB',
    'customerPhone' => '+251911234567',
    'merchantReference' => 'order_123',
    'returnUrl' => 'https://yourstore.com/orders/123/complete',
], idempotencyKey: 'order_123');

// Save $session['reference'], then send the customer to pay.
header('Location: ' . $session['checkoutUrl']);

$epay = new Epay(['timeout' => 10.0, 'max_retries' => 3]);

$epay->mode();       // 'live' | 'sandbox' | null
$epay->isSandbox();  // bool

use GuzzleHttp\Client as GuzzleClient;

$http = new GuzzleClient([
    'proxy' => 'http://proxy.internal:8080',
    'http_errors' => false, // let the SDK map statuses and retry
]);

$epay = new Epay(['api_key' => $key], $http);

$session = $epay->payments->initialize([
    'amount' => 250,                  // string, int, or float
    'currencyCode' => 'etb',          // uppercased
    'customerPhone' => '0911234567',  // rewritten to '+251911234567'
    'merchantReference' => 'order_123',
    'email' => '[email protected]',
    'callbackUrl' => 'https://yourstore.com/webhooks/epay', // overrides the dashboard URL
], idempotencyKey: 'order_123');

$receipt = $epay->payments->verify($reference);
// $receipt['status'] === 'completed', plus serviceFee, paymentMethod, customer

$epay->payments->cancel($reference); // returns void on 204

$transaction = $epay->transactions->retrieve($reference);
$timeline = $epay->transactions->timeline($reference);

foreach ($timeline['events'] as $event) {
    echo $event['eventType'], ' ', $event['occurredAt'], PHP_EOL;
}

foreach ($epay->transactions->list([
    'status' => 'completed',
    'currency' => 'ETB',
    'from' => '2026-08-01',
    'to' => '2026-08-31',
]) as $transaction) {
    echo $transaction['reference'], ' ', $transaction['amount'], PHP_EOL;
}

$page = $epay->transactions->list();
$page->data();       // exactly this page, no extra requests
$page->hasMore();    // bool
$page->nextPage();   // the next TransactionPage, or null

$recent = $epay->transactions->list()->toArray(50);   // cap the walk

foreach ($epay->transactions->list()->pages() as $page) {  // page at a time
    processBatch($page->data());
}

$epay->paymentProviders->list();         // compact, for dropdowns
$epay->paymentProviders->getAll();       // with category and isEnabled
$epay->paymentProviders->listEnabled();  // only what you can route to today

use Epay\Exception\EpayWebhookSignatureException;

$raw = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EPAY_SIGNATURE'] ?? null;

try {
    $event = $epay->webhooks->constructEvent($raw, $signature);
} catch (EpayWebhookSignatureException $error) {
    http_response_code(401);
    exit;
}

// Acknowledge fast, process later.
enqueue($event);
http_response_code(200);

match ($event['event']) {
    'payment.success' => fulfil($event['reference']),
    'payment.failed', 'payment.cancelled' => release($event['reference']),
    'payment.refunding', 'payment.refunded', 'payment.reversed' => reconcile($event),
    default => null, // an event this SDK version does not know yet
};

use Epay\Epay;

final class CheckoutController
{
    public function __construct(private readonly Epay $epay) {}

    public function store(Request $request)
    {
        $session = $this->epay->payments->initialize([
            'amount' => $request->string('amount')->value(),
            'currencyCode' => 'ETB',
            'customerPhone' => $request->string('phone')->value(),
            'merchantReference' => $order->id,
        ], idempotencyKey: $order->id);

        return redirect()->away($session['checkoutUrl']);
    }
}

use Epay\Laravel\VerifyEpayWebhook;

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: ['webhooks/epay']);
    $middleware->alias(['epay.webhook' => VerifyEpayWebhook::class]);
})

use Epay\Laravel\VerifyEpayWebhook;

Route::post('/webhooks/epay', function (Request $request) {
    $event = VerifyEpayWebhook::event($request);

    ProcessEpayEvent::dispatch($event); // acknowledge fast, process later

    return response()->noContent(200);
})->middleware('epay.webhook');

use Epay\Exception\EpayApiException;
use Epay\Exception\EpayBadRequestException;
use Epay\Exception\EpayNotFoundException;
use Epay\Exception\EpayRateLimitException;

try {
    $receipt = $epay->payments->verify($reference);
} catch (EpayNotFoundException) {
    return null;
} catch (EpayBadRequestException) {
    return 'not settled yet';
} catch (EpayRateLimitException $error) {
    sleep((int) ($error->retryAfterSeconds() ?? 1));
    throw $error;
} catch (EpayApiException $error) {
    Log::error('ePay failure', [
        'status' => $error->status,
        'request' => $error->request,
        'body' => $error->body,
    ]);
    throw $error;
}

$data = $epay->request('GET', '/some/new/endpoint', ['limit' => 10]);

sh
composer 

sh
php artisan vendor:publish --tag=epay-config