README

GoPay PHP SDK

SDK PHP officiel pour l'API GoPAY — Paiement & Payout Mobile Money

Intégrez l'API GoPAY en quelques minutes dans vos projets PHP natif, Laravel ou Symfony.

Installation · Démarrage rapide · Laravel · Symfony · PHP natif · Gestion des erreurs · Référence API

✅ Prérequis

📦 Installation

composer require mecxer713/gopay-php

⚡ Démarrage rapide

use Mecxer713\GoPay\GoPayService;

$gopay = new GoPayService(
    baseUrl:          'https://gopay.gooomart.com',
    paymentApiKey:    'votre_api_key',
    paymentSecretKey: 'votre_secret_key',
    payoutApiKey:     'votre_payout_api_key',
);

// Initier un paiement
$response = $gopay->initPayment(4000, 'CDF', '+24399000000', 'REF-001');

if ($response->isSuccessful()) {
    echo $response->transId;           // TRANS-001.94786.53389
    echo $response->transactionStatus; // "success"
    echo $response->amount;            // "4000"
    echo $response->currency;          // "CDF"
}

🔷 Laravel

1. Configuration

Le package supporte Laravel Package Auto-Discovery. Aucune déclaration manuelle n'est nécessaire.

Publiez le fichier de configuration :

php artisan vendor:publish --provider="Mecxer713\GoPay\GoPayServiceProvider" --tag="gopay-config"

Ajoutez vos clés dans le fichier .env :

GOPAY_BASE_URL=https://gopay.gooomart.com
GOPAY_API_KEY=votre_cle_api
GOPAY_SECRET_KEY=votre_cle_secrete
GOPAY_PAYOUT_API_KEY=votre_cle_api_payout

2. Via la Facade

use Mecxer713\GoPay\Facades\GoPay;

// Initier un paiement
$response = GoPay::initPayment(4000, 'CDF', '+24399000000', 'REF-001');

if ($response->isSuccessful()) {
    $transId = $response->transId;
}

// Vérifier le statut d'un paiement
$check = GoPay::checkPayment('REF-001');
echo $check->transactionStatus; // "success", "pending", ...

3. Via l'injection de dépendances

use Mecxer713\GoPay\GoPayServiceInterface;

class PaymentController extends Controller
{
    public function __construct(private GoPayServiceInterface $gopay) {}

    public function pay(): JsonResponse
    {
        $response = $this->gopay->initPayment(4000, 'CDF', '+24399000000', 'REF-001');

        return response()->json([
            'success' => $response->isSuccessful(),
            'trans_id' => $response->transId,
        ]);
    }
}

🟣 Symfony

1. Activer le Bundle

Dans config/bundles.php (si Flex ne l'a pas fait automatiquement) :

return [
    // ...
    Mecxer713\GoPay\Symfony\GoPayBundle::class => ['all' => true],
];

2. Créer la configuration

config/packages/go_pay.yaml :

go_pay:
    base_url:       '%env(GOPAY_BASE_URL)%'
    api_key:        '%env(GOPAY_API_KEY)%'
    secret_key:     '%env(GOPAY_SECRET_KEY)%'
    payout_api_key: '%env(GOPAY_PAYOUT_API_KEY)%'

.env :

GOPAY_BASE_URL=https://gopay.gooomart.com
GOPAY_API_KEY=votre_cle_api
GOPAY_SECRET_KEY=votre_cle_secrete
GOPAY_PAYOUT_API_KEY=votre_cle_api_payout

3. Utilisation via l'injection de dépendances

use Mecxer713\GoPay\GoPayServiceInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class PaymentController extends AbstractController
{
    public function __construct(private GoPayServiceInterface $gopay) {}

    public function pay(): Response
    {
        $balance = $this->gopay->getPayoutBalance();

        return $this->json(['balance' => $balance->balance]);
    }
}

🔧 PHP Natif

require 'vendor/autoload.php';

use Mecxer713\GoPay\GoPayService;

$gopay = new GoPayService(
    baseUrl:          'https://gopay.gooomart.com',
    paymentApiKey:    'votre_api_key',
    paymentSecretKey: 'votre_secret_key',
    payoutApiKey:     'votre_payout_api_key',
);

$balance = $gopay->getPayoutBalance();
echo $balance->balance; // 5000.0

📖 Référence API

💳 Payment API

initPayment() — Initier un paiement

$response = $gopay->initPayment(
    amount:    4000,
    devise:    'CDF',
    telephone: '+24399000000',
    myref:     'REF-001',
    usersId:   null // optionnel
);

Retourne : PaymentResponse

checkPayment() — Vérifier le statut

$response = $gopay->checkPayment(ref: 'REF-001');

Retourne : PaymentResponse

💸 Payout API

getPayoutBalance() — Solde du wallet

$response = $gopay->getPayoutBalance();

echo $response->balance;  // 5000.0
echo $response->currency; // "USD"

Retourne : PayoutBalanceResponse

sendPayoutTransfer() — Envoyer de l'argent

$response = $gopay->sendPayoutTransfer(
    montant:    500,
    devise:     'CDF',
    telephones: ['0991234567', '0811234567'],
    myrefs:     ['ref-001', 'ref-002'],
    dateDenvoi: null // optionnel : "2024/12/25 14:00"
);

Retourne : PayoutTransferResponse

getPayoutTransferStatus() — Statut d'un transfert

$response = $gopay->getPayoutTransferStatus(transIdOrMyref: 'TRANS-001.94786.53389');

echo $response->transactionStatus; // "EN ATTENTE" | "TRAITÉE" | "REJETÉE"

Retourne : PayoutTransferResponse

getPayoutTransfers() — Liste des transferts

$transfers = $gopay->getPayoutTransfers(); // array brut

deletePayoutTransfer() — Supprimer un transfert

⚠️ Seuls les transferts au statut EN ATTENTE peuvent être supprimés.

$response = $gopay->deletePayoutTransfer(transId: 'TRANS-001.94786.53389');

Retourne : PayoutTransferResponse

🗂 Objets de Réponse (DTOs)

Toutes les méthodes retournent des objets PHP fortement typés, avec autocomplétion IDE complète.

PaymentResponse

Méthode helper : isSuccessful(): bool

PayoutBalanceResponse

Méthode helper : isSuccessful(): bool

PayoutTransferResponse

Méthode helper : isSuccessful(): bool

🚨 Gestion des Erreurs

Le SDK retourne directement le corps de la réponse de l'API pour que vous puissiez inspecter toutes les informations en cas d'erreur logique (success: false). Les exceptions ne sont levées qu'en cas d'erreur de communication réseau ou de configuration.

Hiérarchie des exceptions

\Exception
└── GoPayException          — erreur réseau ou décodage JSON
    └── ConfigurationException — clés API manquantes

Exemple complet

use Mecxer713\GoPay\Exception\GoPayException;
use Mecxer713\GoPay\Enums\GoPayErrorCode;

try {
    $response = GoPay::initPayment(4000, 'CDF', '+24399000000', 'REF-001');

    if ($response->isSuccessful()) {
        // Traitement du succès
        $transId = $response->transId;
    } else {
        // Erreur retournée par l'API GoPAY
        echo $response->message;     // "Aucune transaction..."
        echo $response->errorCode;   // "ERR_NO_PAYMENT_FOUND"

        // Comparaison typée via l'enum
        if ($response->errorCode === GoPayErrorCode::TIMESTAMP_EXPIRED->value) {
            // Le timestamp est trop ancien, relancer la requête
        }

        // Accès aux données brutes de la réponse, ex: transaction: {status: 'failed'}
        $raw = $response->raw;
    }

} catch (GoPayException $e) {
    // Erreur réseau, timeout, ou JSON invalide
    echo $e->getMessage();
}

Codes d'erreur (GoPayErrorCode)

🧪 Tests

# Lancer les tests
composer test

# Analyse statique (PHPStan)
composer analyse

# Formatage du code (Laravel Pint)
composer format

📄 Changelog

Consultez le fichier CHANGELOG.md pour l'historique des versions.

🤝 Contribution

Les contributions sont les bienvenues ! Pour contribuer :

1. Forkez le dépôt
2. Créez une branche : git checkout -b feature/ma-fonctionnalite
3. Committez vos changements avec des messages clairs
4. Ouvrez une Pull Request

Assurez-vous que les tests passent avant de soumettre : composer test.

📃 Licence

Ce package est distribué sous la licence MIT. Consultez le fichier LICENSE pour plus de détails.