Search by

mercy-pay / mercy-pay-php

gessyken

Bibliothèque PHP officielle de l'API Mercy Pay : paiements mobile money et carte en Afrique.

v0.2.0 2026-11-18 02:37 UTC

This package is auto-updated.

Last update: 2026-11-18 10:00:43 UTC


README

La bibliothèque PHP officielle de l'API Mercy Pay : paiements mobile money et carte.

PHP 8.2 ou plus, avec curl et json. Aucune autre dépendance.

composer require mercy-pay/mercy-pay-php

Sur Laravel, prenez plutôt mercy-pay/laravel : configuration, façade et route de webhooks prêtes.

Encaisser un paiement

use MercyPay\MercyPayClient;

$mercyPay = new MercyPayClient(getenv('MERCY_PAY_API_KEY'));

$session = $mercyPay->checkoutSessions->create([
    'amount' => 15000,
    'currency' => 'XAF',
    'description' => 'Commande 4821',
    'success_url' => 'https://boutique.example/merci',
    'metadata' => ['order_id' => '4821'],
]);

header('Location: '.$session->checkout_url);

Les montants sont en unités mineures. Chaque objet se lit en propriété ou en tableau : $session->status ou $session['status']. toArray() le rend en tableau.

Recevoir les webhooks

use MercyPay\Exception\SignatureVerificationException;
use MercyPay\Webhook;

$payload = file_get_contents('php://input');

try {
    $event = Webhook::constructEvent($payload, $_SERVER['HTTP_MERCYPAY_SIGNATURE'] ?? null, getenv('MERCY_PAY_WEBHOOK_SECRET'));
} catch (SignatureVerificationException) {
    http_response_code(400);
    exit;
}

if ($event->type === 'payment.succeeded') {
    $orderId = $event->data->metadata['order_id'];
    // Marquez la commande comme payée.
}

http_response_code(200);

Passez le corps brut, avant tout json_decode. Les événements inconnus de votre code sont à ignorer avec un 200.

Listes

Les listes arrivent par pages, les plus récents d'abord :

foreach ($mercyPay->payments->all(['limit' => 100])->autoPagingIterator() as $payment) {
    // Toutes les pages, chargées au fur et à mesure.
}

Erreurs

use MercyPay\Exception\ApiConnectionException;
use MercyPay\Exception\InvalidRequestException;
use MercyPay\Exception\PaymentException;

try {
    $mercyPay->payouts->create($params, ['idempotency_key' => "payout-{$id}"]);
} catch (InvalidRequestException $e) {
    $e->getErrorCode(); // validation_failed, insufficient_balance…
    $e->getParam();     // le champ en cause
} catch (PaymentException $e) {
    // Refusé par l'opérateur ou la banque.
} catch (ApiConnectionException $e) {
    // Pas de réponse : relancez avec la même idempotency_key.
}

Toutes les exceptions héritent de MercyPay\Exception\MercyPayException. getRequestId() donne l'identifiant à citer au support.

Nouvelles tentatives et idempotence

Une coupure réseau, un 429 ou une erreur 5xx sont retentés deux fois. Chaque POST porte une Idempotency-Key, la même à chaque tentative : un paiement ou un retrait n'est jamais créé en double. Pour couvrir aussi vos propres relances, passez votre clé : ['idempotency_key' => "order-{$id}"].

Options

new MercyPayClient($apiKey, [
    'timeout' => 30,        // secondes
    'max_retries' => 2,
    'http_client' => $client, // votre MercyPay\HttpClient\ClientInterface
]);

Paramètres décrits

Chaque méthode décrit les clés que l'API accepte, en forme de tableau PHPDoc : PhpStorm les propose, et PHPStan signale une clé obligatoire oubliée ou une valeur inconnue. Les opérateurs, les pays et les types d'événements sont dans MercyPay\Catalog :

use MercyPay\Catalog;

$mercyPay->payments->create([
    'amount' => 1000,
    'currency' => 'XAF',
    'country' => 'CMR',
    'provider' => Catalog::MTN_MOMO_CMR,
    'phone' => '237653456789',
], ['idempotency_key' => 'order-4821']);

Attendre le résultat

Pour un script ou un test, attendez qu'un paiement ait un statut final :

$payment = $mercyPay->payments->waitForFinalStatus($id, ['timeout' => 60_000]);
$session = $mercyPay->checkoutSessions->waitForCompletion($sessionId);

La lecture se répète, de plus en plus espacée. Passé le délai, WaitTimeoutException donne le dernier état dans $last. Sur un serveur en production, préférez le webhook payment.succeeded.

Sandbox

Une clé mp_sandbox_… ne touche pas à l'argent réel.

// Le numéro de test qui produit ce résultat :
$phone = $mercyPay->testHelpers->mobileMoneyNumber(Catalog::ORANGE_CMR, 'insufficient_balance');

Les résultats possibles : succeeded, pending, payout_failed, ou un failure_code comme insufficient_balance. $mercyPay->testHelpers->triggerEvent(['type' => 'payment.succeeded']) envoie un événement de test à vos endpoints. La CLI relaie les webhooks vers votre ordinateur.

Développement

vendor/bin/phpunit lance les tests, sans réseau. tests/fixtures/openapi.json est une copie de la référence de l'API : python3 scripts/generate.py régénère les services et le catalogue, et un test vérifie que chaque endpoint a sa méthode.

Documentation

La référence de chaque endpoint est sur docs.mercy-pay.com. Le nom de chaque méthode suit celui de la référence : $mercyPay->subscriptions->pause($id), $mercyPay->webhookEndpoints->rotateSecret($id)…

tests/fixtures/openapi.json est une copie de la référence : un test vérifie que chaque endpoint a sa méthode.