# Nelsius Pay - Guide API Universelle (V1)

Nelsius Pay est une infrastructure de paiement sans frontières. Cette documentation regroupe nos solutions de paiement globales et locales.

### 🛠️ Ressources pour Développeurs
- **Postman** : [Importer la collection V1](https://god.gw.postman.com/run-collection/41238945-9e3b09f6-f20a-4302-b6d2-8d7a21904666?action=collection_import)
- **SDK PHP** : `composer require nelsius/nelsius-pay-php` ([GitHub](https://github.com/nelson-siebi/nelsius-pay-php))
- **SDK Node.js** : `npm install nelsius-pay-node` ([GitHub](https://github.com/nelson-siebi/nelsius-pay-node))

### 🌎 Une Couverture Sans Limite
Nelsius supporte les transactions dans **tous les pays du monde**. Grace à notre réseau de partenaires et nos passerelles multi-devises, vous pouvez encaisser vos clients quel que soit leur emplacement géographique.

## 1. Une Seule Intégration, Plusieurs Mondes
Nous regroupons les meilleures méthodes de paiement pour maximiser votre taux de conversion :
- **Cartes Bancaires** (Global) : Visa, Mastercard, American Express.
- **PayPal** (International) : Le standard mondial pour les paiements en ligne.
- **Crypto-monnaies** (Web3) : +100 actifs supportés (USDT, BTC, ETH...) sur plusieurs réseaux.
- **Mobile Money** (Afrique) : Le moyen de paiement local par excellence.

---

## 2. Authentification
Toutes les requêtes doivent inclure votre clé secrète dans le header HTTP :
`Authorization: Bearer sk_live_...`

> [!IMPORTANT]
> Ne partagez jamais votre clé secrète. Utilisez la clé `Public` pour le frontend et la clé `Secret` pour votre serveur.

---

## 2. Paiements (Charges)

### 2.1 Paiement Direct (Mobile Money)

Le paiement direct permet de déclencher une demande de débit (Push USSD) sur le téléphone du client.

**Endpoint:** `POST /api/v1/payments/mobile-money`

### 3.1 Direct Pay (Support Spécialisé en Afrique ⚡)
Pour les pays suivants, Nelsius permet un débit **Direct** (Push USSD) sans sortie de votre application :

| Pays | Drapeaux | Devise | Opérateurs Directs |
| :--- | :--- | :--- | :------- |
| **Cameroun** | 🇨🇲 | `XAF` | `mtn_money`, `orange_money` |
| **Bénin** | 🇧🇯 | `XOF` | `mtn_money`, `moov_money` |
| **Burkina Faso** | 🇧🇫 | `XOF` | `orange_money`, `moov_money` |
| **Togo** | 🇹🇬 | `XOF` | `tmoney`, `moov_money` |
| **Côte d'Ivoire** | 🇨🇮 | `XOF` | `orange_money`, `mtn_money`, `moov_money`, `wave` |
| **RD Congo** | 🇨🇩 | `CDF` | `vodacom_money`, `airtel_money`, `orange_money` |
| **Congo** | 🇨🇬 | `XAF` | `airtel_money`, `mtn_money` |

*Note: Pour tous les autres pays, utilisez le **Hosted Checkout** pour profiter du support universel (Cartes, PayPal).*

*Note: Pour tous les autres pays, utilisez le **Hosted Checkout** pour profiter du support universel (Cartes, PayPal).*

#### Payload de Requête
```json
{
    "amount": 1000,
    "currency": "XAF",
    "operator": "orange_money",
    "phone": "237699000000",
    "description": "Achat de crédit",
    "reference": "REQ_9920",
    "success_url": "https://monsite.com/success",
    "cancel_url": "https://monsite.com/cancel"
}
```

---

### 2.2 Checkout Session (Hébergé)

Pour une intégration plus simple, utilisez nos sessions de checkout hébergées qui gèrent automatiquement le choix de la méthode de paiement pour le client.

**Endpoint:** `POST /api/v1/checkout/sessions`

```json
{
    "amount": 5000,
    "currency": "XAF",
    "reference": "ORDER_123",
    "return_url": "https://monsite.com/callback"
}
```

---

## 3. Retraits (Payouts)

Effectuez des retraits automatiques vers des comptes Mobile Money.

**Endpoint:** `POST /api/v1/withdrawals`

| Paramètre | Type | Description |
| :--- | :--- | :--- |
| `amount` | Float | Montant à retirer |
| `operator` | String | Code opérateur (voir tableau 2.1) |
| `phone_number` | String | Numéro du bénéficiaire |
| `country` | String | Code pays (ex: `CM`, `BJ`) |

---

## 4. Webhooks

Configurez une URL Webhook dans votre dashboard pour recevoir des notifications en temps réel.

### Sécurité
Chaque notification inclut une signature `X-Nelsius-Signature` calculée via HMAC-SHA256 en utilisant votre `API-SECRET` comme clé.

### Format du Payload
```json
{
    "event": "payment.success",
    "data": {
        "transaction_code": "TRX-123",
        "reference_id": "REFE-456",
        "status": "completed",
        "amount": "1000.00",
        "currency": "XAF"
    },
    "timestamp": 1709234850,
    "horodatage": 1709234850
}
```

> [!TIP]
> Le champ `horodatage` est le champ recommandé pour récupérer la date/heure de l'événement. Le champ `timestamp` est conservé pour la compatibilité.

---

## SDKs Officiels

Pour accélérer votre développement, utilisez nos SDKs officiels qui gèrent l'authentification et les appels API pour vous.

### PHP SDK
Installation :
```bash
composer require nelsius/nelsius-pay-php
```
Usage rapide :
```php
$client = new NelsiusClient(['api_key' => 'sk_live_...']);
$session = $client->checkout->createSession(['amount' => 1000, 'currency' => 'XOF']);
```
👉 [Lien GitHub & Documentation complète](https://github.com/nelson-siebi/nelsius-pay-php)

### Node.js SDK
Installation :
```bash
npm install nelsius-pay-node
```
Usage rapide :
```javascript
const client = new NelsiusClient({ apiKey: 'sk_live_...' });
const session = await client.checkout.createSession({ amount: 1000, currency: 'XOF' });
```
👉 [Lien GitHub & Documentation complète](https://github.com/nelson-siebi/nelsius-pay-node)

---
*© 2026 Nelsius Pay. Tous droits réservés.*