README

SDK PHP officiel pour l'API HayBTech -- paiement mobile en Afrique de l'Ouest .

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

Versions PHP supportees

Le SDK manipule des cles secretes marchand (sk_live_*) et signe/verifie des webhooks HMAC. A ce titre, HayBTech ne supporte que les versions de PHP qui recoivent encore des correctifs de securite upstream par l'equipe php.net.

Version PHP	Statut SDK	Fin du support securite upstream
8.4	Support actif	31 dec 2028
8.3	Support actif	31 dec 2027
8.2	Support actif (min)	31 dec 2026
8.1	Non supporte (EOL)	31 dec 2025
8.0	Non supporte (EOL)	26 nov 2023
7.4	Non supporte (EOL)	28 nov 2022

Reference officielle : php.net/supported-versions.php

Politique d'EOL

HayBTech retire le support d'une version PHP au plus tard 3 mois apres son EOL upstream. Cette regle est appliquee dans composer.json (require.php) et fait l'objet d'une release MAJOR (semver) avec entree CHANGELOG dediee.

Vous etes bloque sur PHP < 8.2 ? Deux options :

Plugin WooCommerce : haybtech-woocommerce-gateway (PHP 7.4+, polyfills inclus) pour les boutiques WordPress sur hebergement mutualise.
Integration REST directe : l'API https://app.haybtech.com/v1 est documentee et utilisable sans SDK depuis n'importe quel runtime capable de signer un HMAC SHA-256.

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é. Vous pouvez directement utiliser l'API n'importe où dans votre code :

use HayBTech\HayBTech;

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

(Optionnel) Si vous préférez initialiser manuellement, appelez configure() une seule fois au démarrage :

HayBTech::configure('sk_live_votre_cle_secrete');

Paiements

Creer un paiement

Le SDK propose une interface fluide pour rediriger vos clients instantanement :

$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();

Si vous souhaitez recuperer manuellement l'URL ou d'autres donnees :

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

if ($result->successful()) {
    // La requete API a reussi
}

Webhooks

1. Verification des signatures (Inbound)

HayBTech envoie un POST signe a votre callback_url. Utilisez le helper pour securiser 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) {
    // Signature invalide ou attaque par rejeu detectee
    http_response_code(403);
    exit;
}

// Traitement de l'evenement
if ($event['event'] === 'payment.success') {
    $orderId = $event['data']['merchant_ref'];
}

1.bis Verification AUTO (sans `HAYBTECH_WEBHOOK_SECRET`)

Si vous voulez eviter la double configuration (HAYBTECH_SECRET_KEY + HAYBTECH_WEBHOOK_SECRET), utilisez AutoVerifier : il recupere seul le secret HMAC depuis l'API HayBTech (via votre sk_live_*/sk_test_*) et le cache localement. Pattern recommande pour les nouvelles integrations.

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; // HayBTech injoignable → laisse retry
}

Sur rotation cote HayBTech, le cache est automatiquement invalide a la prochaine signature mismatch (un seul retry, pas de boucle). Exemple complet avec fallback safe : examples/webhook-auto-verify.php.

Pour les workers daemon (Horizon, RoadRunner, queue listeners) sans I/O disque, remplacez FilesystemWebhookSecretCache par InMemoryWebhookSecretCache.

2. Gestion des endpoints (Outbound)

Gerez vos URLs de notification programmatique :

// Lister vos endpoints
$endpoints = HayBTech::webhooks()->all();

// Creer un nouvel endpoint
HayBTech::webhooks()->create([
    'url' => 'https://api.monsite.com/hooks',
    'subscribed_events' => ['payment.success']
]);

// Recuperer le secret HMAC d'un endpoint (utilise par AutoVerifier sous le capot).
// L'auth se fait via votre sk_live_*/sk_test_* ; pas d'OTP cote API merchant.
$res = HayBTech::webhooks()->revealSecret($id);
echo $res['secret'];

// Verifier qu'un endpoint joint correctement HayBTech (ping de test).
HayBTech::webhooks()->sendTestPing($id);

// Rechercher un endpoint par URL exacte (anti-doublon a l'installation).
HayBTech::webhooks()->lookup('https://monsite.sn/hooks');

Evenements disponibles

Liste complete des event envoyes a vos endpoints webhook. Abonnez-vous a ce dont vous avez besoin via subscribed_events sur l'endpoint.

Paiements

Evenement	Description
`payment.initiated`	Transaction creee, en attente du payeur
`payment.pending`	PSP a accepte, en attente de confirmation finale
`payment.success`	Paiement confirme
`payment.failed`	Paiement echoue (refus PSP, fonds insuffisants…)
`payment.cancelled`	Annule par le client
`payment.expired`	Delai d'attente PSP depasse
`payment.updated`	Metadata ou statut intermediaire mis a jour

Payouts (transferts sortants)

Evenement	Description
`payout.success`	Payout confirme cote PSP
`payout.failed`	Payout rejete (KYC, beneficiaire invalide)
`payout.cancelled`	Annule avant execution
`payout.refunded`	Retourne dans le wallet HayBTech
`payout.partially_refunded`	Retour partiel

Remboursements

Evenement	Description
`refund.success`	Remboursement abouti
`refund.failed`	Remboursement refuse par le PSP

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) {
    // SDK non configure, curl indisponible, cle invalide...
    $e->getMessage();
}

Mode test

HayBTech::configure('sk_test_...'); // aucun debit reel

Utilisation avancee

// Client explicite (multi-compte, timeout custom)
// N'affecte pas le client partage configure via configure()
// Le mode test/live est determine par la cle (sk_test_… vs sk_live_…), pas par l'URL.
$client = HayBTech::client('sk_test_autre_compte', [
    'timeout' => 60,
]);

$client->payments->create([...]);

Securite et Confidentialite

Le SDK integre des mecanismes de protection avances :

Masquage Automatique : Vos cles secretes sont masquees dans les var_dump() pour eviter les fuites dans les logs.
Sanitisation des Erreurs : Les exceptions ApiException filtrent automatiquement les donnees sensibles (CVV, PIN, Secrets) des traces de pile.
Protection DoS : Limite de taille sur les payloads webhooks (1 Mo) pour eviter l'epuisement de la memoire.
Anti-Injection : Protection native contre les injections CRLF dans les headers HTTP.
Zero Dependance : Aucun risque d'attaque par chaine d'approvisionnement (Supply Chain).

Ressources API

Ressource	Description
`HayBTech::payments()`	Creer, recuperer, lister, verifier 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 a approbation ops

Parametres avances pour `payments->create()`

En plus des champs documentés ci-dessus (merchant_ref, amount, currency, success_url, failed_url, callback_url), payments->create() accepte :

Champ	Valeurs	Description
`payin_fee_mode`	`merchant` / `customer` / `split`	Qui supporte les frais HayBTech. `merchant` = vous (defaut). `customer` = montant majore au payeur.
`metadata.payment_channel`	`push`	Active la branche Orange Money Push (paiement direct sans saisie code marchand cote payeur). Necessite l'activation `om_push_payment_enabled` cote admin + provider account configure (MSISDN partenaire + PIN chiffre).
`metadata.*`	scalar libre	Tout couple cle/valeur relaye intact dans les webhooks (commande interne, user_id, etc.).

Exemple OM Push :

$result = HayBTech::payments()->create([
    'merchant_ref' => 'CMD-' . uniqid(),
    'amount'       => 25000,
    'currency'     => 'XOF',
    'provider'     => 'orange_money_sn',
    'callback_url' => 'https://monsite.sn/webhook',
    'metadata'     => [
        'payment_channel' => 'push',
        'customer_msisdn' => '+221771234567',
    ],
]);

Statut d'une transaction (cas webhook PSP perdu)

// payments->retrieve() lit la ligne locale uniquement (rapide, peut etre perime).
$txn = HayBTech::payments()->retrieve('TXN-abc123');

// status->retrieve() pull aussi le PSP si la ligne locale est non-terminale.
// A privilegier quand vous soupconnez un statut periode (sandbox, timeout, etc.).
$txn = HayBTech::status()->retrieve('TXN-abc123');

Publier sur Packagist

Cette section s'adresse aux mainteneurs du SDK.

1. Pousser sur GitHub

git remote add origin https://github.com/haybtech/php-sdk.git
git push -u origin main --tags

2. Soumettre sur Packagist

packagist.org > Submit
URL : https://github.com/haybtech/php-sdk > Check > Submit

3. Webhook GitHub (mises a jour automatiques)

GitHub > Settings > Webhooks > Add webhook :

Champ	Valeur
Payload URL	`https://packagist.org/api/github?username=haybtech`
Content type	`application/json`
Secret	votre token API Packagist
Events	Just the push event

4. Publier une nouvelle version

git tag v1.1.0 && git push origin main --tags
# Packagist est notifie automatiquement

Respectez semver : PATCH (bug fix) . MINOR (nouvelle feature) . MAJOR (breaking change).

MIT License

haybtech / php-sdk

Maintainers

Package info

Statistics

Security

README

Intégration par IA (Prompt pour Marchands)

Installation

Versions PHP supportees

Politique d'EOL

Configuration (Zéro-Config)

Paiements

Creer un paiement

Webhooks

1. Verification des signatures (Inbound)

1.bis Verification AUTO (sans `HAYBTECH_WEBHOOK_SECRET`)

2. Gestion des endpoints (Outbound)

Evenements disponibles

Paiements

Payouts (transferts sortants)

Remboursements

Gestion des erreurs

Mode test

Utilisation avancee

Securite et Confidentialite

Ressources API

Parametres avances pour `payments->create()`

Statut d'une transaction (cas webhook PSP perdu)

Publier sur Packagist

1. Pousser sur GitHub

2. Soumettre sur Packagist

3. Webhook GitHub (mises a jour automatiques)

4. Publier une nouvelle version

haybtech / php-sdk

Maintainers

Package info

Statistics

Security

README

Intégration par IA (Prompt pour Marchands)

Installation

Versions PHP supportees

Politique d'EOL

Configuration (Zéro-Config)

Paiements

Creer un paiement

Webhooks

1. Verification des signatures (Inbound)

1.bis Verification AUTO (sans HAYBTECH_WEBHOOK_SECRET)

2. Gestion des endpoints (Outbound)

Evenements disponibles

Paiements

Payouts (transferts sortants)

Remboursements

Gestion des erreurs

Mode test

Utilisation avancee

Securite et Confidentialite

Ressources API

Parametres avances pour payments->create()

Statut d'une transaction (cas webhook PSP perdu)

Publier sur Packagist

1. Pousser sur GitHub

2. Soumettre sur Packagist

3. Webhook GitHub (mises a jour automatiques)

4. Publier une nouvelle version

1.bis Verification AUTO (sans `HAYBTECH_WEBHOOK_SECRET`)

Parametres avances pour `payments->create()`