README

Official PHP SDK for Zayono, the unified Mobile Money payment gateway for Africa.

Wraps the Zayono REST API with authentication, automatic retries, idempotency, lazy pagination, typed exceptions, and webhook signature verification.

• Package: zayono/zayono-php
• Source: github.com/RomualdAKM/zayono-php
• Documentation: docs.zayono.com/sdks/php

Requirements

• PHP 8.1 or higher
• ext-json
• Guzzle 7 (or any PSR-18 HTTP client)

Installation

composer require zayono/zayono-php

Quick start

use Zayono\Zayono;

$zayono = new Zayono('zyn_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');

$payment = $zayono->payments->create([
    'amount'         => 5000,
    'currency'       => 'XOF',
    'description'    => 'T-shirt premium',
    'customer_email' => 'customer@example.com',
    'return_url'     => 'https://example.com/success',
    'cancel_url'     => 'https://example.com/cancel',
]);

header('Location: ' . $payment['checkout_url']);

Configuration

$zayono = new Zayono(
    apiKey:     'zyn_test_xxxxx',
    baseUrl:    'https://backend.zayono.com/api/v1',  // default
    timeout:    30,                                    // seconds
    maxRetries: 3,                                     // 5xx + 429 + network
    logger:     $psrLogger,                            // optional PSR-3
);

The environment (sandbox vs live) is derived server-side from the API key prefix:

• zyn_test_* keys produce sandbox-environment transactions
• zyn_live_* keys produce production transactions

Examples

1. Initialize a payment

$payment = $zayono->payments->create([
    'amount'         => 5000,
    'currency'       => 'XOF',
    'description'    => 'Order #1234',
    'customer_email' => 'jean@example.com',
    'metadata'       => ['order_id' => 'ORD-1234'],
]);

echo $payment['checkout_url'];

2. Retrieve and verify a payment

$payment = $zayono->payments->retrieve('019e5eaf-cb99-7351-a6d5-c219e28534db');

if ($payment['status'] === 'success') {
    // Deliver the order.
}

// Force a fresh check against the upstream aggregator:
$payment = $zayono->payments->verify('019e5eaf-cb99-7351-a6d5-c219e28534db');

3. Send a payout

$payout = $zayono->payouts->create([
    'amount'      => 10000,
    'currency'    => 'XOF',
    'operator'    => 'mtn_bj',
    'phone'       => '+22961000000',
    'description' => 'Payout for order ORD-1234',
]);

Refunds: the public API-key v1 surface does not yet expose POST /v1/payments/{id}/refunds. For now, trigger refunds from the Zayono merchant dashboard. A refunds resource will be added to this SDK once the endpoint ships on the v1 surface.

4. Verify a webhook signature

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ZAYONO_SIGNATURE'] ?? '';

if (!$zayono->webhooks->verify($payload, $signature, getenv('ZAYONO_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);

match ($event['event']) {
    'payment.succeeded' => handlePaymentSuccess($event['data']),
    'payment.failed'    => handlePaymentFailure($event['data']),
    default             => null,
};

5. Paginate through every payment

foreach ($zayono->payments->list(['status' => 'success']) as $payment) {
    echo $payment['id'], PHP_EOL;
}

For a single page:

$page = $zayono->payments->listPage(['status' => 'success', 'per_page' => 50]);
foreach ($page['payments'] as $payment) {
    // …
}

Idempotency

Every POST, PATCH, PUT, and DELETE request automatically receives a fresh X-Idempotency-Key (UUID v4) so retried calls never double-process a transaction. Override the key explicitly when you need to:

$zayono->payments->create([
    'amount'           => 5000,
    'currency'         => 'XOF',
    'idempotency_key'  => '019e5eaf-cb99-4351-a6d5-c219e28534db',
]);

Retries

Transient failures are retried 3 times by default with exponential backoff (250 ms → 1 s → 4 s):

• Network errors (DNS, connect, timeout)
• HTTP 429 (respects Retry-After)
• HTTP 502 / 503 / 504

4xx responses (other than 429) are never retried.

Error handling

Every API error is mapped to a typed exception extending Zayono\Exceptions\ZayonoException:

use Zayono\Exceptions\{
    AuthenticationException,
    ValidationException,
    RateLimitException,
    ResourceNotFoundException,
    ServerException,
    NetworkException,
};

try {
    $payment = $zayono->payments->create([/* … */]);
} catch (ValidationException $e) {
    foreach ($e->errors as $field => $messages) {
        echo "$field: ", implode(', ', $messages), PHP_EOL;
    }
} catch (AuthenticationException $e) {
    // 401: key revoked / wrong / expired
} catch (RateLimitException $e) {
    sleep($e->retryAfter ?? 1);
} catch (ResourceNotFoundException $e) {
    // 404
} catch (ServerException $e) {
    // 5xx after exhausting retries
} catch (NetworkException $e) {
    // No response received after retries
}

Every exception exposes:

• getStatusCode(): ?int: HTTP status (when applicable)
• getErrors(): ?array: server-side errors envelope field
• getRequestId(): ?string: X-Request-Id header value for support tickets

Logging

The SDK accepts any PSR-3 logger. Requests log at info; 4xx/5xx and retries log at warning.

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('zayono');
$log->pushHandler(new StreamHandler('zayono.log'));

$zayono = new Zayono('zyn_test_xxxxx', logger: $log);

PSR-18 / custom HTTP clients

Swap Guzzle for any PSR-18 implementation by passing it to the constructor:

$zayono = new Zayono(
    apiKey:     'zyn_test_xxxxx',
    httpClient: $myPsr18Client,
);

Testing

composer install
composer test

License

MIT © Zayono