SDK PHP

Le SDK PHP officiel. Requiert PHP 8.2+ et s'installe via Composer.

Intégration par IA (Prompt pour Marchands)

Si vous utilisez un assistant IA (comme Cursor, GitHub Copilot, ChatGPT, Claude, etc.), vous pouvez copier-coller le prompt suivant pour intégrer ce SDK de A à Z dans votre projet :

Agis en tant qu'expert en développement PHP. Je souhaite intégrer la solution de paiement HayBTech (Afrique de l'Ouest) sur mon site marchand de A à Z avec le SDK PHP officiel `haybtech/php-sdk`.

Voici ma stack technique actuelle :
- Framework : [ex: Laravel, Symfony, PHP Pur/MVC]
- Base de données & ORM : [ex: Eloquent, Doctrine, PDO]
- Modèle de commande : [décrivez brièvement votre structure de table Order]

Tâches à accomplir dans le code généré :
1. **Configuration** : Initialiser le SDK HayBTech (`HayBTech::configure(...)` ou via la clé `HAYBTECH_SECRET_KEY` dans le fichier `.env`).
2. **Création du Paiement** : Créer un contrôleur de checkout. Récupérer la commande, appeler `HayBTech::payments()->create([...])` avec `merchant_ref`, `amount`, `currency` (XOF), `success_url`, `failed_url`, et `callback_url`. Rediriger automatiquement le client avec la méthode `$result->redirect()` ou renvoyer l'URL.
3. **Webhook de Validation** : Créer la route de webhook. Elle doit :
   - Récupérer le flux brut (`file_get_contents('php://input')`) et le header `HTTP_X_HAYBTECH_SIGNATURE`.
   - Valider la signature via `HayBTech::webhook()::constructEvent(...)` ou `AutoVerifier` pour sécuriser l'endpoint sans faille de sécurité.
   - Vérifier de manière idempotente si la commande n'est pas déjà validée en base de données.
   - Traiter `payment.success` (livrer la commande/passer le statut à payé) et `payment.failed` (annuler la commande).
   - Renvoyer un code HTTP 200.
4. **Sécurité & Gestion des Erreurs** : Gérer les exceptions `ApiException` et `SignatureException` de manière sécurisée en masquant les données sensibles dans les logs.

Génère un code propre, conforme aux bonnes pratiques PHP modernes (PSR), bien commenté et prêt à l'emploi.

Installation

composer require haybtech/php-sdk

Configuration (Zéro-Config)

Si vous utilisez un framework (Laravel, Symfony) ou un fichier .env, vous n'avez rien à configurer. Ajoutez simplement votre clé dans votre environnement :

HAYBTECH_SECRET_KEY=sk_live_votre_cle_secrete

Le SDK détectera automatiquement votre clé :

use HayBTech\HayBTech;

$result = HayBTech::payments()->create([...]);

(Optionnel) Si vous préférez initialiser manuellement :

HayBTech::configure('sk_live_votre_cle_secrete');

Créer un paiement

use HayBTech\HayBTech;

$result = HayBTech::payments()->create([
    'merchant_ref' => 'CMD-' . uniqid(),
    'amount'       => 25000,
    'currency'     => 'XOF',
    'success_url'  => 'https://monsite.sn/succes',
    'failed_url'   => 'https://monsite.sn/annulation',
    'callback_url' => 'https://monsite.sn/webhook',
]);

// Redirection automatique vers le guichet de paiement
$result->redirect();

Récupérer manuellement l'URL ou d'autres données :

$paymentUrl = $result['data']['payment_url'];
$txnId      = $result['data']['id'];

if ($result->successful()) {
    // La requête API a réussi
}

Vérification webhook

HayBTech envoie un POST signé à votre callback_url. Utilisez le helper pour sécuriser votre endpoint :

use HayBTech\Exceptions\SignatureException;

try {
    $event = HayBTech::webhook()::constructEvent(
        file_get_contents('php://input'),
        $_SERVER['HTTP_X_HAYBTECH_SIGNATURE'] ?? '',
        getenv('HAYBTECH_WEBHOOK_SECRET')
    );
} catch (SignatureException $e) {
    http_response_code(403);
    exit;
}

if ($event['event'] === 'payment.success') {
    $orderId = $event['data']['merchant_ref'];
}

AutoVerifier (recommandé pour les nouvelles intégrations)

Évitez la double configuration (HAYBTECH_SECRET_KEY + HAYBTECH_WEBHOOK_SECRET) avec AutoVerifier :

use HayBTech\HayBTechClient;
use HayBTech\Webhook\AutoVerifier;
use HayBTech\Webhook\FilesystemWebhookSecretCache;

$client = new HayBTechClient(getenv('HAYBTECH_SECRET_KEY'));
$cache  = new FilesystemWebhookSecretCache(__DIR__ . '/storage/hayb-cache');
$auto   = new AutoVerifier($client, $cache);

try {
    $event = $auto->constructEvent(
        file_get_contents('php://input'),
        $_SERVER['HTTP_X_HAYBTECH_SIGNATURE'] ?? '',
        getenv('HAYBTECH_WEBHOOK_ENDPOINT_ID')
    );
} catch (\HayBTech\Exceptions\SignatureException $e) {
    http_response_code(403); exit;
} catch (\HayBTech\Exceptions\HayBTechException $e) {
    http_response_code(503); exit;
}

Usage (Laravel)

use HayBTech\HayBTech;

class CheckoutController extends Controller
{
    public function pay(Request $request)
    {
        $result = HayBTech::payments()->create([
            'merchant_ref' => 'ORDER-' . $request->order_id,
            'amount'       => $request->amount,
            'currency'     => 'XOF',
            'success_url'  => route('orders.success', $request->order_id),
            'failed_url'   => route('orders.cancel', $request->order_id),
            'callback_url' => route('webhooks.haybtech'),
        ]);

        return redirect()->away($result['data']['payment_url']);
    }

    public function webhook(Request $request)
    {
        try {
            $event = HayBTech::webhook()::constructEvent(
                $request->getContent(),
                $request->header('X-HayBTech-Signature'),
                config('services.haybtech.webhook_secret')
            );
        } catch (\HayBTech\Exceptions\SignatureException $e) {
            return response()->json(['error' => 'Invalid signature'], 403);
        }

        if ($event['event'] === 'payment.success') {
            // Marquer la commande comme payée
        }

        return response()->json(['ok' => true]);
    }
}

Exclure la route webhook du CSRF

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'webhooks/haybtech',
    ]);
})

Mode test

HayBTech::configure('sk_test_...'); // Aucun débit réel

Gestion des erreurs

use HayBTech\Exceptions\ApiException;
use HayBTech\Exceptions\HayBTechException;

try {
    $result = HayBTech::payments()->create($params);
} catch (ApiException $e) {
    $e->getMessage();    // Message lisible
    $e->getHttpStatus(); // 400, 422, 500...
    $e->getErrorCode();  // ex. "insufficient_funds"
    $e->isRetryable();   // true si 5xx ou 429 → retry avec backoff
} catch (HayBTechException $e) {
    $e->getMessage();
}

Tests Pest

use Illuminate\Support\Facades\Http;

it('creates a payment and follows the payment_url', function () {
    Http::fake([
        'app.haybtech.com/*' => Http::response(['data' => [
            'id'          => 'fake-uuid',
            'payment_url' => 'https://app.haybtech.com/pay/checkout/fake-uuid',
        ]], 201),
    ]);

    $result = HayBTech::payments()->create([
        'merchant_ref' => 'TEST-001',
        'amount'       => 5000,
        'currency'     => 'XOF',
        'success_url'  => 'https://monsite.sn/succes',
        'failed_url'   => 'https://monsite.sn/annulation',
    ]);

    expect($result['data']['payment_url'])->toContain('/pay/checkout/');
});

Versions PHP supportées

Version PHP	Statut SDK	Fin du support sécurité upstream
8.4	Support actif	31 déc 2028
8.3	Support actif	31 déc 2027
8.2	Support actif (min)	31 déc 2026
8.1	Non supporté (EOL)	31 déc 2025

Bloqué sur PHP < 8.2 ? Utilisez le plugin WooCommerce Gateway (PHP 7.4+).

Ressources API

Ressource	Description
HayBTech::payments()	Créer, récupérer, lister, vérifier des paiements + splits marketplace
HayBTech::refunds()	Initier des remboursements (totaux ou partiels)
HayBTech::payouts()	Envoyer des fonds vers un wallet mobile money
HayBTech::payoutRequests()	Soumettre une demande de retrait soumise à approbation ops
HayBTech::balance()	Solde disponible et réserve par devise
HayBTech::webhooks()	Gérer vos endpoints de notification (sortants)
HayBTech::webhook()	Vérifier les signatures de webhooks entrants
HayBTech::health()	Endpoint de healthcheck (sondes uptime)