Facturation & Webhooks — Ash-Wallet

Ash-Wallet sert d'orchestrateur intelligent et sécurisé. Il gère la réception des webhooks des passerelles de paiement (FedaPay, FeexPay) et la réexpédition (dispatching) d'événements unifiés vers votre propre backend.

---

1. Réception des Webhooks (Passerelle → Ash Gateway)

Pour enregistrer et suivre l'avancement des transactions, Ash Gateway expose des endpoints publics pour les webhooks des agrégateurs :

A. Configuration FedaPay

• URL du Webhook : https://app.ashgateway.com/fedapay/webhook/:projectId (où :projectId est l'ID ou le slug de votre projet).
• Sécurisation : Copiez le Webhook Secret généré par FedaPay dans les paramètres de votre projet sur Ash Gateway. Les signatures de FedaPay (header x-fedapay-signature) seront alors validées à l'aide de l'algorithme HMAC-SHA256 par notre serveur.

B. Configuration FeexPay

• URL du Webhook : https://app.ashgateway.com/feexpay/webhook/:projectId.

---

2. Dispatch des Webhooks unifiés (Ash Gateway → Votre Backend)

Dès qu'un paiement change de statut (création, succès, ou échec), Ash Gateway expédie une requête HTTP POST à l'URL de webhook configurée dans vos paramètres de projet.

Payload unifié

{
  "event": "payment.success",
  "data": {
    "id": "603d2e1b4f1a2c001f789abc",
    "amount": 5000,
    "currency": "XOF",
    "status": "success",
    "provider": "fedapay",
    "providerPaymentId": "123456",
    "metadata": {}
  }
}

Événements et statuts

• payment.initiated : Paiement en cours de traitement (statut: initiated).
• payment.success : Paiement approuvé et finalisé (statut: success).
• payment.failed : Paiement échoué, annulé ou décliné (statut: failed).

---

3. Sécurisation avec X-Ashgate-Signature

Toutes les requêtes envoyées à votre serveur d'application contiennent l'en-tête X-Ashgate-Signature. Cette signature est générée à l'aide de l'algorithme HMAC-SHA256 avec :

• Le corps brut de la requête (raw JSON string).
• La Secret Key (secretKey) de votre projet (commençant par sk_...).

Exemple de vérification (Node.js/Express)

const crypto = require('crypto');

app.post('/webhooks/ashgate', express.json(), (req, res) => {
  const signature = req.headers['x-ashgate-signature'];
  const secretKey = process.env.ASHGATE_PROJECT_SECRET; // sk_...

  const expectedSig = crypto
    .createHmac('sha256', secretKey)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(400).json({ error: 'Signature invalide' });
  }

  // Traiter l'événement
  const { event, data } = req.body;
  if (event === 'payment.success') {
    // Valider la commande...
  }

  res.status(200).json({ received: true });
});

---

4. Stratégie de Retry

Si votre serveur ne répond pas avec un code HTTP 200 OK dans un délai de 3 secondes, Ash Gateway retentira de délivrer le webhook jusqu'à 3 fois avec un délai d'attente de 5 secondes entre chaque tentative.