Download the PHP package epay-et/php-sdk without Composer

epay-et/php-sdk

Official ePay Business API client for PHP, with a Laravel integration.

Accept payments from every major Ethiopian mobile wallet and bank with one integration.

Full API documentation: https://docs.epayethiopia.com/

• PHP 8.1+, typed throughout, PSR-4 and PSR-18
• Automatic retries with exponential backoff and jitter on 429/5xx/network errors
• Safe retries on initialize — every attempt reuses one idempotency key
• Exact decimal amounts via bcmath, with a string-comparison fallback
• Constant-time webhook verification with hash_equals
• Laravel: auto-discovered service provider, publishable config, webhook middleware

Install

Quick start

The key prefix picks the environment: sk_test_… runs against the sandbox and sk_live_… moves real money. There is no separate mode to configure.

Configuration

Every option falls back to an environment variable, so new Epay() is enough.

(string) $epay and var_dump($epay) both mask the key, so a client is safe to log.

Bring your own HTTP client

The second constructor argument takes any PSR-18 client — for connection pooling, an outbound proxy, or mTLS:

Leave http_errors off: the SDK maps non-2xx responses itself so the retry policy and error hierarchy stay in one place.

Payments

Initialize

amount, currencyCode, and customerPhone are validated locally, so a typo throws EpayValidationException immediately instead of costing a round trip.

On amounts. Pass a string. Integers and floats are accepted and rounded half-up to two places, but floats cannot represent every decimal amount exactly. The result always carries two decimal places.

On idempotency keys. If you omit idempotencyKey, the SDK generates a fresh one per call. That makes its internal retries safe — a retried initialize cannot double-charge — but it does not deduplicate across separate calls. Pass your own order id to get that guarantee.

Verify before fulfilling

The API rejects a transaction that is not yet completed, so use transactions->retrieve first if you would rather branch on status than catch an EpayBadRequestException.

Cancel

Only pending and processing transactions can be cancelled, and cancellation is irreversible. This call is never retried automatically, because the endpoint takes no idempotency key.

Transactions

Listing and pagination

The endpoint is cursor-paginated at a fixed 10 per page. Iterate a page to walk every following page, fetching lazily and carrying your filters along:

from and to accept a string or any DateTimeInterface, and the API caps the range at 90 days.

Other ways to consume the same endpoint:

Payment providers

Both endpoints are mode-aware and permission-gated: list needs list_platform_payment_provider, getAll needs get_platform_payment_provider.

Webhooks

Verify the X-Epay-Signature header against the raw request body before you trust a payload. Re-encoding a decoded array can reorder keys and change the digest, which rejects valid deliveries.

constructEvent fails closed: any event it returns had a valid signature.

Handling events

ePay retries anything that is not a 2xx within 10 seconds, up to 5 attempts, so keep the handler fast and make it idempotent — deduplicate on $event['reference'].

Laravel

The service provider is auto-discovered. Add your keys to .env:

Then inject the client anywhere:

Publish the config to change defaults:

Webhook middleware

ePay sends no CSRF token, so exclude the route and alias the middleware. In bootstrap/app.php (Laravel 11+):

On Laravel 10, add 'webhooks/epay' to $except in app/Http/Middleware/VerifyCsrfToken.php and register the alias in app/Http/Kernel.php.

Then the route:

The middleware rejects a bad or missing signature with 401 before your route runs, and VerifyEpayWebhook::event() throws rather than returning an unverified payload if the middleware was not applied.

Error handling

Every failure extends EpayException. HTTP failures carry the status, parsed body, and response headers.

429, 5xx, and network errors are retried automatically before surfacing.

Sandbox testing

Use a sk_test_… key with the documented magic phone numbers:

Generate a fresh idempotency key per test run: reusing one returns the cached response instead of triggering the scenario again.

Testing your own code

Pass a scripted PSR-18 client and no request leaves the process — see tests/ClientTest.php for a ready-made ScriptedHttpClient.

Unmodelled endpoints

$epay->request() reaches anything this version does not wrap yet, with the same auth, timeout, retry, and error handling:

Development

Releasing

CI runs the suite on PHP 8.1 through 8.4 — including a lowest dependency resolution on 8.1, so the declared minimum constraints are proven to work, not just the newest releases — plus PHPStan level 8, php-cs-fixer, and composer validate --strict.

One-time setup:

1. Submit the repository at packagist.org/packages/submit.
2. Enable the Packagist GitHub integration so new tags publish automatically (Packagist → your profile → Settings, or the repo's webhook settings).

Optional fallback, only if you do not set up that integration: add the repository secrets PACKAGIST_USERNAME and PACKAGIST_TOKEN. The release workflow then pings the Packagist API itself, and skips that step when the secrets are absent.

To release:

Packagist derives the version from the tag — there is no build step and nothing to upload. release.yml therefore runs the full check suite on the tag as a gate, because a published version cannot be withdrawn.

Note that Composer reads composer.json from the repository root, which is why this SDK lives in its own repository rather than a subdirectory.

License

MIT