waslpay/core-php

Unified mobile-money payment SDK core for PHP.

v3.0.3 2026-07-24 11:48 UTC

Requires

• php: >=8.1
• guzzlehttp/psr7: ^2.0
• psr/http-client: ^1.0
• psr/http-message: ^1.0 || ^2.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.0
• phpunit/phpunit: ^10.0

MIT

Published on Packagist.org on 2026-07-24 12:16 UTC

README

SDK PHP 8.1+ fondé sur PSR-18, PSR-7 et des DTO immuables.

Installation

composer require waslpay/core-php

Pour développer ce monorepo :

composer install

Configuration et initialisation

Injectez un client HTTP PSR-18 et le provider choisi dans la façade.

<?php

use GuzzleHttp\Client;
use WaslPay\Sdk\WaslPay;
use WaslPay\Sdk\Providers\WaveProvider;

$provider = new WaveProvider(
    new Client(),
    getenv('WAVE_API_KEY'),
    getenv('WAVE_WEBHOOK_SECRET'),
);
$waslPay = new WaslPay($provider);

Variables .env :

ORANGE_MONEY_CLIENT_ID=
ORANGE_MONEY_CLIENT_SECRET=
ORANGE_MONEY_MERCHANT_CODE=
ORANGE_MONEY_SITENAME=
ORANGE_MONEY_CALLBACK_URL=
ORANGE_MONEY_WEBHOOK_API_KEY=
ORANGE_MONEY_ENVIRONMENT=sandbox
WAVE_API_KEY=
WAVE_WEBHOOK_SECRET=
MTN_MOMO_SUBSCRIPTION_KEY=
MTN_MOMO_API_USER=
MTN_MOMO_API_KEY=
MTN_MOMO_TARGET_ENVIRONMENT=sandbox
MTN_MOMO_DEFAULT_CURRENCY=XOF

OrangeMoneyProvider reçoit le client PSR-18, les credentials OAuth, le contexte marchand et la clé webhook. MtnMomoProvider reçoit le client, la subscription key, l'API user, l'API key, l'environnement et la devise par défaut.

Flux de paiement complet

<?php

declare(strict_types=1);

use WaslPay\Sdk\DTO\PaymentRequest;

// 1. Créer une session.
$session = $waslPay->initiatePayment(new PaymentRequest(
    amount: 1000,
    currency: 'XOF',
    reference: 'order-123',
    customerPhone: '[phone]',
    successUrl: 'https://merchant.example/payments/success',
    failureUrl: 'https://merchant.example/payments/failed',
));

// 2. Vérifier le statut.
$statusResult = $waslPay->checkStatus($session->id);
if ($statusResult->status === PaymentStatus::Failed) {
    $error = $statusResult->error;
}

// 3. Une route webhook doit transmettre le body brut, sans json_decode préalable.
$rawBody = file_get_contents('php://input');
$event = $waslPay->handleWebhook($rawBody, getallheaders());

// 4. Rembourser. Orange Money rejette explicitement cette opération.
$refund = $waslPay->refund($session->id, 500);

Traitez PaymentEvent::$id de manière idempotente et répondez seulement après validation du header de sécurité par l'adaptateur.

Erreurs normalisées

PaymentError	Orange Money	Wave	MTN MoMo
INSUFFICIENT_FUNDS	2020, 2021	insufficient-funds	NOT_ENOUGH_FUNDS
PROVIDER_TIMEOUT	Erreurs techniques	HTTP 5xx ou timeout	HTTP 5xx ou timeout
INVALID_PHONE	2000, 2001	Mismatch du mobile	Validation MSISDN/provider
USER_CANCELLED	Annulation client	Paiement annulé	APPROVAL_REJECTED, EXPIRED
UNKNOWN	Autre erreur	Autre erreur	Autre erreur

Les adaptateurs lèvent ProviderException; consultez sa propriété paymentError pour appliquer une décision métier sûre.

Tester sans clés API

Lancez waslpay dev, puis passez http://localhost:4004/mock/wave comme dernier argument baseUrlOverride du vrai WaveProvider. En production, retirez seulement cette URL et remplacez les valeurs d'environnement.

Tests

vendor/bin/phpunit

Les classes de tests provider étendent le contrat réutilisable et utilisent des clients HTTP mockés.