PHPackages                             haybtech/php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. haybtech/php-sdk

ActiveLibrary[Payment Processing](/categories/payments)

haybtech/php-sdk
================

SDK PHP officiel pour l'API HayBTech — agrégateur de paiement Afrique de l'Ouest.

v1.0.0(2w ago)01↓100%MITPHPPHP ^8.2

Since May 22Pushed 1w agoCompare

[ Source](https://github.com/HayBTech/haybtech-php-sdk-)[ Packagist](https://packagist.org/packages/haybtech/php-sdk)[ RSS](/packages/haybtech-php-sdk/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

HayBTech PHP SDK
================

[](#haybtech-php-sdk)

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

[![Packagist](https://camo.githubusercontent.com/343e7102d4580472317f1a9ac3b4ccc7b75b65cea8ebfd8784982cc548a21e8c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f68617962746563682f7068702d73646b2e737667)](https://packagist.org/packages/haybtech/php-sdk)[![PHP](https://camo.githubusercontent.com/c9f64f714c636ba27a3bba6dfd52f98426832db1262747efa54b212d16943651/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e322d626c7565)](https://php.net)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)

---

Intégration par IA (Prompt pour Marchands)
------------------------------------------

[](#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
------------

[](#installation)

```
composer require haybtech/php-sdk
```

---

Versions PHP supportees
-----------------------

[](#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 PHPStatut SDKFin du support securite upstream**8.4**Support actif31 dec 2028**8.3**Support actif31 dec 2027**8.2**Support actif (min)31 dec 20268.1Non supporte (EOL)31 dec 20258.0Non supporte (EOL)26 nov 20237.4Non supporte (EOL)28 nov 2022> Reference officielle : [php.net/supported-versions.php](https://www.php.net/supported-versions.php)

### Politique d'EOL

[](#politique-deol)

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 :

1. **Plugin WooCommerce** : `haybtech-woocommerce-gateway` (PHP 7.4+, polyfills inclus) pour les boutiques WordPress sur hebergement mutualise.
2. **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)
---------------------------

[](#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
---------

[](#paiements)

### Creer un paiement

[](#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
--------

[](#webhooks)

### 1. Verification des signatures (Inbound)

[](#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`)

[](#1bis-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`](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)

[](#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
----------------------

[](#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

[](#paiements-1)

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

[](#payouts-transferts-sortants)

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

[](#remboursements)

EvenementDescription`refund.success`Remboursement abouti`refund.failed`Remboursement refuse par le PSP---

Gestion des erreurs
-------------------

[](#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
---------

[](#mode-test)

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

---

Utilisation avancee
-------------------

[](#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
---------------------------

[](#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
--------------

[](#ressources-api)

RessourceDescription`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| `HayBTech::balance()` | Solde disponible et reserve par devise | | `HayBTech::providers()` | Liste des PSP actifs (Orange Money SN/CI, Wave, OMD…) | | `HayBTech::status()` | Statut transaction avec pull PSP si non-terminal (cas webhook perdu) | | `HayBTech::disputes()` | Lister et repondre aux disputes mobile money | | `HayBTech::settlements()` | Lister les virements vers le compte marchand | | `HayBTech::webhooks()` | Gerer vos endpoints de notification (sortants) | | `HayBTech::webhook()` | Verifier les signatures de webhooks entrants | | `HayBTech::health()` | Endpoint de healthcheck (sondes uptime) |

---

Parametres avances pour `payments->create()`
--------------------------------------------

[](#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 :

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

[](#statut-dune-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
---------------------

[](#publier-sur-packagist)

> Cette section s'adresse aux **mainteneurs** du SDK.

### 1. Pousser sur GitHub

[](#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

[](#2-soumettre-sur-packagist)

1. [packagist.org](https://packagist.org) > **Submit**
2. URL : `https://github.com/haybtech/php-sdk` > **Check** > **Submit**

### 3. Webhook GitHub (mises a jour automatiques)

[](#3-webhook-github-mises-a-jour-automatiques)

GitHub > **Settings > Webhooks > Add webhook** :

ChampValeurPayload URL`https://packagist.org/api/github?username=haybtech`Content type`application/json`Secretvotre token API PackagistEvents*Just the push event*### 4. Publier une nouvelle version

[](#4-publier-une-nouvelle-version)

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

Respectez [semver](https://semver.org/lang/fr/) : `PATCH` (bug fix) . `MINOR` (nouvelle feature) . `MAJOR` (breaking change).

MIT License

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance97

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

18d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6216ba4e6ef250120e78f3c44b8c261f40e2e833bccc38de1e058a3745b92c44?d=identicon)[HayBTech](/maintainers/HayBTech)

---

Top Contributors

[![MoustaphaMANGANE01](https://avatars.githubusercontent.com/u/53624207?v=4)](https://github.com/MoustaphaMANGANE01 "MoustaphaMANGANE01 (4 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/haybtech-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/haybtech-php-sdk/health.svg)](https://phpackages.com/packages/haybtech-php-sdk)
```

###  Alternatives

[omnipay/coinbase

Coinbase driver for the Omnipay payment processing library

18570.2k1](/packages/omnipay-coinbase)[yenepay/php-sdk

YenePay SDK for PHP

112.7k](/packages/yenepay-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)