barkapay / payhub-php
Official PHP SDK for the barkapay API — mobile-money collections, payouts and hosted payment links, one API across countries.
Requires
- php: ^8.1
- ext-curl: *
- ext-json: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.85
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 21:04:38 UTC
README
Official PHP client for the barkapay API — mobile-money collections, payouts and hosted payment links across West Africa, behind one API.
- Zero runtime dependencies (just
ext-curl+ext-json) — safe to embed inside WordPress / WooCommerce. - Typed, immutable objects for payments, transfers, payment links and balances.
- Webhook signature verification built in.
- Safe by default: TLS always verified, redirects never followed, money-moving calls never replayed blindly.
Available countries: Burkina Faso (bf), Bénin (bj), Sénégal (sn).
Requirements
PHP 8.1+ with the curl and json extensions.
Install
composer require barkapay/payhub-php
Quick start
use PayHub\Client; $barkapay = new Client( apiKey: getenv('PAYHUB_API_KEY') ?: null, // the "key_id:secret" pair from the dashboard country: 'bf', // default country, overridable per call ); $payment = $barkapay->payments->create([ 'operator' => 'ORANGE', // upper case, as listed by operators->info() 'phone_number' => '74123456', // national format, no country code 'amount' => 10000, 'otp' => '123456', // operators that take the payer's code up-front (e.g. ORANGE) 'order' => ['id' => 'ORDER-2026-001', 'unique' => true], ]); echo $payment->publicId, ' ', $payment->rawStatus, PHP_EOL;
Authentication — pass the
key_id:secretpair asapiKey(orkeyIdandsecretseparately). The SDK adds theBearerprefix itself. Keep the key on your server: never ship it to a browser or a mobile app, never commit it.
Every method takes an optional last argument $country to target another country than the
client's default: $barkapay->balance->get('sn').
Payments
use PayHub\Enum\PaymentStatus; use PayHub\Exception\PaymentFailedException; try { $payment = $barkapay->payments->create([ 'operator' => 'MOOV', 'phone_number' => '70123456', 'amount' => 5000, 'order' => ['id' => 'ORDER-2026-002', 'unique' => true], ]); } catch (PaymentFailedException $e) { // The payer or the operator refused. The attempt is recorded on the API side: $failed = $e->getPayment(); // status FAILED error_log('Payment refused: ' . ($failed->reasonCode ?? $e->getMessage())); return; } match ($payment->status) { // Settled in this very response. PaymentStatus::Successful => fulfilOrder($payment->orderId), // The payer received a code by SMS: collect it, then confirm. PaymentStatus::AwaitingOtp => askPayerForOtp($payment->publicId), // The payer approves on their phone (or at $payment->redirectUrl for WAVE): // the verdict arrives by webhook. default => waitForWebhook($payment->publicId), };
What happens after create() depends on the operator — always branch on the returned status:
| Status | Meaning | Operators today |
|---|---|---|
SUCCESSFUL |
Settled synchronously | ORANGE (bf, sn) — the payer's OTP is sent in otp |
AWAITING_OTP |
Call confirmOtp() with the code the payer received |
MOOV (bf) |
PROCESSING_OPERATOR |
The payer approves on their side; the verdict arrives by webhook | MTN (bj), WAVE (sn, open $payment->redirectUrl) |
$barkapay->operators->info() is the authoritative list of operators for a country, with their
amount bounds and whether they need an OTP.
$payment = $barkapay->payments->confirmOtp($publicId, '012345'); // MOOV bf — one attempt only $barkapay->payments->resendOtp($publicId); $payment = $barkapay->payments->get($publicId); // by public_id… $payment = $barkapay->payments->get('ORDER-2026-002'); // …or by your order id (*) $page = $barkapay->payments->list(['status' => 'SUCCESSFUL', 'per_page' => 50]); foreach ($page as $payment) { echo $payment->publicId, ' ', $payment->amount, ' ', $payment->currency, PHP_EOL; }
- (*)
get()cannot look up an order id that is shaped like a UUID (the API reads it as a public id) or that contains a/: uselist(['order_id' => …])for those. phone_numberis the national number, digits only, without the country code: 8 digits in Burkina Faso, 10 in Bénin, 9 in Sénégal.operatoris upper case (ORANGE,MOOV,MTN,WAVE).- The OTP is a string:
'012345'keeps its leading zero,012345does not. EXPIREDmeans the payer never completed (distinct fromFAILED, a real refusal).$payment->isFinal()is true forSUCCESSFUL,FAILED,EXPIREDandCANCELED.- On a failed payment,
reasonCodeis a stable code you can branch on (PayHub\Enum\ReasonCode),reasonits English sentence andproviderReasonthe operator's own words. The status is the verdict; the reason code is only an indication. - A status this SDK version does not know yet gives
$payment->status === null;$payment->rawStatusalways holds the string the API sent.
Payment links
A payment link is a durable URL on the barkapay-hosted checkout: your customer opens it, picks an operator and pays. Nothing to build on your side.
$link = $barkapay->paymentLinks->create([ 'title' => 'Invoice #1234', 'usage' => 'single', // or 'multi' for a reusable link 'amount' => ['type' => 'fixed', 'currency' => 'XOF', 'value' => '25000'], 'order' => ['id' => 'INV-1234'], 'redirect' => ['success_url' => 'https://shop.example/thanks'], ]); echo $link->url, PHP_EOL; // share this with your customer $link = $barkapay->paymentLinks->get($link->publicId); // by PL-… id or by slug $links = $barkapay->paymentLinks->list(['status' => 'active,paused']); $link = $barkapay->paymentLinks->update($link->publicId, ['title' => 'Invoice #1234 (revised)']); $link = $barkapay->paymentLinks->pause($link->publicId); // checkout refuses new payments $link = $barkapay->paymentLinks->resume($link->publicId); $link = $barkapay->paymentLinks->cancel($link->publicId); // for good // Payments made through the link (per country — see below). $payments = $barkapay->paymentLinks->listPayments($link->publicId, ['status' => 'SUCCESSFUL']); echo $payments->paymentLink?->stats?->totalCollected, PHP_EOL;
- A link is not a payment: payments are born when payers pay. They are regular payments
(
channel=hosted,linkPublicIdset) and fire the usualpayment.*webhooks on the API application that created the link. amount.typeisfixed(value),range(min/max) oropen(the payer chooses). Amounts are decimal strings in major units.update()only changestitle,description,expires_atandredirect.pause()andresume()never fail on the link's state: called on a link that is not active (resp. not paused) they return it unchanged — check the returnedstatus.update()andcancel()on a closed link throwValidationException.listPayments()returns the payments held by the country you call. For a link open to several countries, call it once per country; the link'sstatsare global either way.- Required scopes on the API application:
payment_links:create,payment_links:read,payment_links:manage. payments->create()is always a direct payment: hosted checkout goes through this resource only.
Transfers
use PayHub\Exception\ConflictException; use PayHub\Exception\InsufficientBalanceException; use PayHub\Exception\TransferFailedException; try { $transfer = $barkapay->transfers->create([ 'operator' => 'ORANGE', 'phone_number' => '74123456', 'amount' => 50000, 'order' => ['id' => 'PAYOUT-2026-001', 'unique' => true], ]); } catch (InsufficientBalanceException $e) { // Top up the wallet: amount + fees exceed what is available. } catch (ConflictException $e) { // Same order id already used, or a near-identical transfer was sent < 60 s ago. } catch (TransferFailedException $e) { $failed = $e->getTransfer(); // status FAILED, reasonCode, providerReason } $transfer = $barkapay->transfers->get('PAYOUT-2026-001'); $page = $barkapay->transfers->list(['from_date' => '2026-11-01', 'to_date' => '2026-11-30']);
A transfer that is not final (PROCESSING_OPERATOR, UNCERTAIN) is in flight: the payout
may be executing. Never send it again — wait for the webhook or poll transfers->get().
Balance & operators
$balance = $barkapay->balance->get(); // available / total / holds, decimal strings in ->currency echo $balance->available, ' ', $balance->currency, PHP_EOL; $operators = $barkapay->operators->info(); // operators, OTP requirement, amount bounds $availability = $barkapay->operators->availability(); // operational / degraded / down per operator $me = $barkapay->me(); // merchant + API application (scopes, permissions) $pong = $barkapay->ping();
Pagination
List methods return one page: a countable, iterable collection with ->items and ->meta.
$page = 1; do { $payments = $barkapay->payments->list(['page' => $page, 'per_page' => 100]); foreach ($payments as $payment) { // … } $page++; } while ($payments->meta?->hasMore());
Webhooks
Every delivery is signed with the Barkapay-Signature header. Verify it against the raw
request body, with the signing secret (whsec_…) of the webhook:
use PayHub\Exception\SignatureVerificationException; use PayHub\Webhook; $payload = file_get_contents('php://input') ?: ''; $header = $_SERVER['HTTP_BARKAPAY_SIGNATURE'] ?? ''; try { $event = Webhook::parse($payload, $header, getenv('PAYHUB_WEBHOOK_SECRET') ?: ''); } catch (SignatureVerificationException $e) { http_response_code(400); exit; } // $event['type'] is "payment" or "transfer"; $event['status'] is the final status. // Deliveries are at-least-once: deduplicate on $event['event_id']. http_response_code(200);
- The signature is
t=<unix>,v1=<hex>withv1 = HMAC-SHA256("{t}.{rawBody}", secret). The SDK compares in constant time and rejects signatures older than 300 seconds (4th argument). - The body has no
eventfield. Derive the event fromtype+status:payment+SUCCESSFULispayment.succeeded,FAILEDispayment.failed,EXPIREDispayment.expired; same fortransfer. - Answer with any
2xxquickly and do the work afterwards; other answers are retried. Webhook::verify()does the same check and returns a boolean.- Pass the raw body (
php://input), never a re-encodedjson_encode(json_decode(…)): the bytes would differ and the signature would never match. - An empty secret, or a tolerance of 0 or less, throws
ConfigurationException: a missing environment variable fails loudly instead of accepting or silently refusing every delivery.
Errors
Every error returned by the API throws an exception extending PayHub\Exception\ApiException:
| Exception | HTTP | When |
|---|---|---|
ValidationException |
422, 400 | Invalid request — getErrors() maps each field to its messages. Also raised, without field details, when the resource is not in the right state (confirming a payment that is not AWAITING_OTP, editing a closed link) |
AuthenticationException |
401 | Missing or wrong API key |
AuthorizationException |
403, 410, 451 | Missing scope, operator not enabled, IP not allowed, account suspended or closed |
NotFoundException |
404 | Unknown resource, endpoint or country |
ConflictException |
409 | Duplicate: order.unique already used, or the 60 s duplicate-transfer guard |
InsufficientBalanceException |
400 | The wallet cannot cover the transfer |
PaymentFailedException |
424 | Payment refused by the payer or the operator — getPayment() |
TransferFailedException |
424 | Transfer refused by the operator — getTransfer() |
RateLimitException |
429 | Too many requests — getRetryAfter() |
ServiceUnavailableException |
503 | Operator or service temporarily unavailable — getRetryAfter() |
ServerException |
5xx | Unexpected error on the API side |
Outside of API responses: NetworkException (no response received), ConfigurationException
(invalid argument or client configuration) and SignatureVerificationException (webhooks).
Catch everything the SDK throws with PayHub\Exception\PayHubException.
use PayHub\Exception\ApiException; use PayHub\Exception\NetworkException; use PayHub\Exception\ValidationException; try { $barkapay->payments->create($params); } catch (ValidationException $e) { foreach ($e->getErrors() as $field => $messages) { // e.g. "phone_number" => ["…"] } } catch (ApiException $e) { error_log(sprintf( 'barkapay error %s (HTTP %d), request %s: %s', $e->getErrorCode(), // machine-readable: "payment_failed", "operator_unavailable", … $e->getHttpStatus(), $e->getRequestId(), // quote it to support $e->getMessage(), )); } catch (NetworkException $e) { // No response. For a payment or a transfer, do NOT assume it failed — see below. }
ApiException also exposes getData(), getRetryAfter(), getResponseHeaders() /
getResponseHeader('x-ratelimit-remaining') and getResponseBody(). NetworkException::getRequestId()
is the X-Request-Id that was sent — quote it to support to learn whether the request arrived.
A 2xx whose body is not the expected JSON envelope (an HTML page, an empty body, a JSON object
without the resource) throws ApiException too — never an empty object passed off as a success.
After a create call it means "outcome unknown", not "refused": look the operation up.
Retries and safe replays
The SDK retries on its own only what cannot duplicate an operation:
| Request | Retried on |
|---|---|
Reads (get, list, balance, operators, ping, me) |
network errors, 429, 502, 503, 504 |
Writes (create, confirmOtp, resendOtp, update, cancel, pause, resume) |
429 only — the request was not processed |
Waits use exponential backoff with jitter and honour Retry-After. If the API asks for a longer
wait than maxRetryDelay (10 s by default — and never more than 10 s for a write), the error is
thrown at once with getRetryAfter() set, instead of blocking your request. maxRetries
(default 2) bounds the number of extra attempts.
A network error, a timeout or a 5xx on a payment or a transfer is never retried automatically: the API has no idempotency key, and the operation may have gone through. To replay safely yourself:
- always send your own reference in
order.id, withorder.unique => true— the API then refuses a second operation with the same id (ConflictException); - on
NetworkException,ServiceUnavailableExceptionorServerException(any 5xx), look the operation up first:payments->list(['order_id' => $orderId])/transfers->list(['order_id' => $orderId]); - only create it again if that list is empty.
An order.id sent with unique stays taken even when its payment or transfer failed: give
every new attempt its own id (ORDER-42-2, ORDER-42-3…).
Rate limits
Limits are per route family and shared by all the API applications of a merchant. They are operational settings: read them at runtime rather than hard-coding them.
$barkapay->payments->list(); $limit = $barkapay->lastRateLimit(); // from the response that was just received echo $limit?->remaining, ' / ', $limit?->limit, PHP_EOL;
A RateLimitException carries the same information: getRetryAfter() (seconds),
getResponseHeader('x-ratelimit-limit') and getResponseHeader('x-ratelimit-remaining').
Amounts
- Send
amountas an integer or a decimal string (10000,'1500.50') — not as the result of float arithmetic. At most two decimals. amountcomes back as the API's JSON number;fees, balances and payment-link amounts come back as decimal strings ("250.00"). Use integers orbcmathfor arithmetic and comparisons.
Configuration
use PayHub\Client; $barkapay = new Client( apiKey: getenv('PAYHUB_API_KEY') ?: null, country: 'bf', baseUrl: 'https://hub.barkapay.com', // default maxRetries: 2, // 0 disables automatic retries timeout: 40.0, // seconds, whole request (the hub itself answers 503 after 30 s) connectTimeout: 10.0, // seconds, connection only maxRetryDelay: 10.0, // seconds, longest wait between two attempts );
baseUrl must be https://. Plain http:// is accepted for a loopback host only
(localhost, 127.0.0.1, [::1]) — or, when you pass your own httpClient, for a mock server
on another host. It is always refused for a barkapay host.
To use your own HTTP stack, pass httpClient: an implementation of
PayHub\Http\HttpClientInterface (it must verify TLS and must not follow redirects). The
default transport accepts a custom CA bundle — new CurlClient(caBundle: '/path/cacert.pem') —
and offers no way to turn certificate verification off.
$barkapay->lastRequestId() returns the X-Request-Id of the latest call, for your logs.
Security
- TLS certificates and host names are always verified; redirects are never followed (a
3xxis an error); plainhttp://is refused outside of loopback (see Configuration). - A response body larger than 10 MiB is refused (
NetworkException). - The API key never appears in exception messages nor in dumps of the client (
var_dump(),print_r(),var_export(),dd()), and PHP 8.2+ redacts it from the stack traces of the SDK and of its default transport. TheRequestobject handed to a custom HTTP client does carry theAuthorizationheader: log$request->redactedHeaders(), never the object. - Identifiers and country codes are validated and percent-encoded before they reach a URL: an
empty identifier,
.,.., or one containing/,?,#or a control character is refused before any request; a country code is two letters. - See SECURITY.md to report a vulnerability.
Upgrading from 1.0
1.1 is backward compatible. Worth knowing:
- writes are no longer replayed after a network error, a timeout or a 503 (they could be executed twice) — only after a 429 asking for 10 s or less;
- the default timeout is 40 s (was 30 s) and
maxRetryDelay10 s; baseUrlmust behttps://unless it is a loopback host or you pass your ownhttpClient;Webhook::verify()/parse()throwConfigurationExceptionfor an empty secret or a tolerance of 0 or less (0 used to switch the replay check off);EXPIREDpayments andUNCERTAINtransfers now have an enum case (they used to hydrate asstatus === null);- the webhook header is
Barkapay-Signature($_SERVER['HTTP_BARKAPAY_SIGNATURE']) — the oldPayHub-Signaturename is no longer sent; - deduplicate webhooks on
event_id.
See CHANGELOG.md for the full list.
License
MIT.