# WPay PHP SDK

[![Latest Version](https://img.shields.io/packagist/v/webcoompay-bj/php-sdk.svg)](https://packagist.org/packages/webcoompay-bj/php-sdk)
[![PHP Version](https://img.shields.io/packagist/php-v/webcoompay-bj/php-sdk.svg)](https://packagist.org/packages/webcoompay-bj/php-sdk)
[![License](https://img.shields.io/packagist/l/webcoompay-bj/php-sdk.svg)](LICENSE)

SDK PHP officiel pour l'API **WPay** — vérification de transactions, orders et webhooks.

## Installation

```bash
composer require webcoompay-bj/php-sdk
```

**Prérequis :** PHP 8.1+ avec les extensions `json` et `hash`.

## Configuration

Tout ce dont vous avez besoin pour démarrer :

```php
use WPay\WPay;

WPay::setSecretKey($_ENV['WPay_SECRET_KEY']);
```

C'est tout. Le SDK cible la production par défaut.

### Variables d'environnement recommandées

```env
# Obligatoires
WPay_SECRET_KEY=sk_live_xxxxxxxxxxxx
```

> 🔒 Stockez toujours la `secret key` dans un `.env` (jamais en dur dans le code, jamais dans git).

## Transactions

```php
// Récupérer une transaction
$tx = WPay::transaction()->retrieve('01kmryyv98aw0mja47zp6h55tk');

// ✅ Vérification complète d'un paiement (statut + montant)
$valid = WPay::transaction()->verifyPayment($txId, expectedAmount: 5000);

// Vérifications séparées
$ok       = WPay::transaction()->isSuccessful($txId);
$amountOk = WPay::transaction()->verifyAmount($txId, 5000.00);

// Liste paginée
$list = WPay::transaction()->list([
    'status'   => 'success',
    'from'     => '2026-01-01',
    'per_page' => 20,
]);
```

## Webhooks — vérification de signature

Le SDK supporte deux formats de signature dans l'en-tête `X-WPay-Signature` :

| Format                    | Header                       | Anti-replay                     |
| ------------------------- | ---------------------------- | ------------------------------- |
| **Horodaté** (recommandé) | `t=1715610000,v1=<hex_hmac>` | ✅ rejette les requêtes > 5 min |
| **Legacy**                | `<hex_hmac>`                 | ❌                              |

## Exceptions

| Exception                   | Code     | Cause                                         |
| --------------------------- | -------- | --------------------------------------------- |
| `AuthenticationException`   | 401/403  | Secret key invalide ou révoquée               |
| `NotFoundException`         | 404      | Ressource introuvable                         |
| `WebhookSignatureException` | 400      | Signature HMAC invalide, manquante ou expirée |
| `WPay`                      | variable | Autre erreur (5xx, réseau, etc.)              |

Toutes héritent de `WPay` qui hérite elle-même de `RuntimeException` — un seul `catch (WPay $e)` capture tout.

## Sécurité

- ✅ HMAC SHA-256 avec `hash_equals` (timing-safe)
- ✅ Anti-replay via timestamp signé (tolérance 5 min)
- ✅ Vérification SSL forcée
- ✅ Retry exponentiel sur erreurs réseau transitoires

Pour signaler une vulnérabilité : **security@webcoompay.com**

## Licence

MIT — voir [LICENSE](LICENSE).