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

Dépendance	Version minimale
PHP	`^8.1`
Guzzle HTTP	`^7.2`
Laravel (optionnel)	`^9.0 \| ^10.0 \| ^11.0`
Symfony (optionnel)	`^5.4 \| ^6.0 \| ^7.0`

📦 Installation

composer require mecxer713/gopay-php

SDK mobiles

Les SDK mobiles sont des paquets autonomes, installables séparément des sources PHP après leur publication : Android/Kotlin via Gradle et JitPack, Flutter/Dart via pub.dev (flutter pub add gopay). Chacun contient sa propre implémentation HTTP et HMAC GoPAY. Comme ils signent les requêtes depuis l'application, les secrets intégrés au binaire peuvent être extraits ; un backend reste préférable pour une utilisation en production.

Leurs versions et procédures de sortie sont indépendantes. Voir VERSIONING.md pour la politique SemVer et les tags android-vX.Y.Z et flutter-vX.Y.Z.

⚡ 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`

Propriété	Type	Description
`$success`	`bool`	`true` si la requête a réussi
`$transactionStatus`	`?string`	Statut textuel de la transaction (ex: `"success"`)
`$transId`	`?string`	Identifiant unique de la transaction
`$url`	`?string`	URL de redirection (si applicable)
`$state`	`?string`	État interne de la transaction
`$message`	`?string`	Message humain retourné par l'API
`$amount`	`?string`	Montant de la transaction
`$currency`	`?string`	Devise (ex: `"CDF"`, `"USD"`)
`$source`	`?string`	Source de la transaction (ex: `"API"`)
`$date`	`?string`	Date ISO de la transaction
`$raw`	`array`	Réponse JSON brute complète

Méthode helper : isSuccessful(): bool

`PayoutBalanceResponse`

Propriété	Type	Description
`$success`	`bool`	`true` si la requête a réussi
`$balance`	`float`	Solde du wallet
`$currency`	`?string`	Devise du solde
`$message`	`?string`	Message de l'API
`$raw`	`array`	Réponse JSON brute complète

Méthode helper : isSuccessful(): bool

`PayoutTransferResponse`

Propriété	Type	Description
`$success`	`bool`	`true` si la requête a réussi
`$transactionStatus`	`?string`	Statut (`"EN ATTENTE"`, `"TRAITÉE"`, `"REJETÉE"`)
`$transId`	`?string`	Identifiant unique du transfert
`$state`	`?string`	État interne
`$message`	`?string`	Message de l'API
`$amount`	`?string`	Montant du transfert
`$currency`	`?string`	Devise
`$source`	`?string`	Source
`$date`	`?string`	Date ISO du transfert
`$raw`	`array`	Réponse JSON brute complète

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`)

Enum	Valeur	Description
`APIKEY_MISSING`	`ERR_APIKEY_MISSING`	Header `x-api-key` absent
`SIGNATURE_MISSING`	`ERR_SIGNATURE_MISSING`	Header `x-signature` absent
`TIMESTAMP_MISSING`	`ERR_TIMESTAMP_MISSING`	Header `x-timestamp` absent
`NONCE_MISSING`	`ERR_NONCE_MISSING`	Header `x-nonce` absent
`APIKEY_INVALID`	`ERR_APIKEY_INVALID`	Clé API invalide
`APIKEY_FORBIDDEN`	`ERR_APIKEY_FORBIDDEN`	Permissions insuffisantes
`APIKEY_INACTIVE`	`ERR_APIKEY_INACTIVE`	Clé API désactivée
`SIGNATURE_INVALID`	`ERR_SIGNATURE_INVALID`	Signature HMAC incorrecte
`TIMESTAMP_EXPIRED`	`ERR_TIMESTAMP_EXPIRED`	Timestamp expiré (> 120 sec)
`NONCE_REPLAY`	`ERR_NONCE_REPLAY`	Nonce déjà utilisé
`VALIDATION`	`ERR_VALIDATION`	Paramètres invalides
`NO_PAYMENT_FOUND`	`ERR_NO_PAYMENT_FOUND`	Transaction introuvable

🧪 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.

Version	Changements clés
`v1.3.1`	Mise à jour de `.env.example` pour inclure la clé Payout et corrections mineures
`v1.3.0`	Refactoring architectural : séparation en PaymentService, PayoutService et HTTP Client
`v1.2.0`	Refactoring complet : enums, DTOs enrichis, helpers, ServiceProvider amélioré
`v1.1.x`	Gestion des erreurs API, support clés `success`/`transaction`
`v1.0.x`	Version initiale

🤝 Contribution

Les contributions sont les bienvenues ! Pour contribuer :

Forkez le dépôt
Créez une branche : git checkout -b feature/ma-fonctionnalite
Committez vos changements avec des messages clairs
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.

Développé par Mecxer713 · Propulsé par GoPAY

mecxer713 / gopay-php

Package info

Security

Statistics

README

GoPay PHP SDK

✅ Prérequis

📦 Installation

SDK mobiles

⚡ Démarrage rapide

🔷 Laravel

1. Configuration

2. Via la Facade

3. Via l'injection de dépendances

🟣 Symfony

1. Activer le Bundle

2. Créer la configuration

3. Utilisation via l'injection de dépendances

🔧 PHP Natif

📖 Référence API

💳 Payment API

initPayment() — Initier un paiement

checkPayment() — Vérifier le statut

💸 Payout API

getPayoutBalance() — Solde du wallet

sendPayoutTransfer() — Envoyer de l'argent

getPayoutTransferStatus() — Statut d'un transfert

getPayoutTransfers() — Liste des transferts

deletePayoutTransfer() — Supprimer un transfert

🗂 Objets de Réponse (DTOs)

PaymentResponse

PayoutBalanceResponse

PayoutTransferResponse

🚨 Gestion des Erreurs

Hiérarchie des exceptions

Exemple complet

Codes d'erreur (GoPayErrorCode)

🧪 Tests

📄 Changelog

🤝 Contribution

📃 Licence

`initPayment()` — Initier un paiement

`checkPayment()` — Vérifier le statut

`getPayoutBalance()` — Solde du wallet

`sendPayoutTransfer()` — Envoyer de l'argent

`getPayoutTransferStatus()` — Statut d'un transfert

`getPayoutTransfers()` — Liste des transferts

`deletePayoutTransfer()` — Supprimer un transfert

`PaymentResponse`

`PayoutBalanceResponse`

`PayoutTransferResponse`

Codes d'erreur (`GoPayErrorCode`)