Architecture multi-passerelle paiement (Wave + OM + Stripe) : le pattern qui marche en 2026

Quand vous franchissez 10M FCFA de volume mensuel, la marge de l'agrégateur (1 %–2.5 % de tout votre CA) devient une ligne de coût critique. Une architecture multi-passerelle vous permet d'utiliser PayDunya pour les paiements XOF, Stripe pour les paiements EUR, et l'API Wave Business directe pour économiser sur le canal n°1.

TL;DR

- Pattern : un service PaymentRouter qui choisit la passerelle selon (devise, pays, montant, dispo).

- Bénéfices : −0.5 % à −1.2 % de frais, fallback automatique, reporting unifié.

- Coût initial : ~2 semaines dev pour la version v1, ROI < 4 mois si volume > 10M.

Schéma d'architecture

`

[Site frontend]

↓

[PaymentRouter]

/ | \

↓ ↓ ↓

[Wave direct] [PayDunya] [Stripe]

\ | /

\ ↓ /

[PaymentEvents DB]

↓

[Reporting unifié]

`

Code : PaymentRouter (TypeScript)

`ts

// lib/payments/router.ts

import { wavePay } from './gateways/wave';

import { paydunyaPay } from './gateways/paydunya';

import { stripePay } from './gateways/stripe';

interface PaymentRequest {

orderId: string;

amount: number;

currency: 'XOF' | 'EUR' | 'USD';

buyerCountry: string;

preferredMethod?: 'wave' | 'om' | 'card';

}

export async function routePayment(req: PaymentRequest) {

const { currency, buyerCountry, preferredMethod, amount } = req;

// Règle 1 : Stripe pour EUR/USD

if (currency === 'EUR' || currency === 'USD') {

return stripePay(req);

}

// Règle 2 : Wave direct si méthode préférée + dispo

if (preferredMethod === 'wave' && (await isWaveHealthy())) {

try {

return await wavePay(req);

} catch (e) {

console.warn('[PaymentRouter] Wave direct failed, fallback PayDunya', e);

return paydunyaPay(req);

}

}

// Règle 3 : OM via PayDunya (pas d'API directe rentable < 50M/mois)

if (preferredMethod === 'om') {

return paydunyaPay(req);

}

// Règle 4 : par défaut, PayDunya (couvre Wave + OM + carte)

return paydunyaPay(req);

}

async function isWaveHealthy(): Promise {

// Cache Redis 30s

const cached = await redis.get('wave:health');

if (cached !== null) return cached === '1';

try {

const res = await fetch(${WAVE_API}/health, { signal: AbortSignal.timeout(2000) });

const ok = res.ok;

await redis.setex('wave:health', 30, ok ? '1' : '0');

return ok;

} catch {

await redis.setex('wave:health', 30, '0');

return false;

}

}

`

Économies réelles (cas client Kolonell)

Boutique mode haut de gamme à Dakar, 18M FCFA/mois sur 12 mois :

Soit ~1.92M FCFA d'économie sur 12 mois pour un investissement initial de 2.5M FCFA. ROI = 7.6 mois.

Reporting unifié

Tous les événements paiement passent par la table PaymentEvent quel que soit le provider :

`prisma

model PaymentEvent {

id String @id @default(cuid())

externalId String @unique

provider String // wave | paydunya | stripe | orange-money

orderId String

amount Int // toujours en plus petite unité (XOF entier, cents EUR)

currency String

status String // success | failed | pending

payload Json

receivedAt DateTime @default(now())

@@index([orderId])

@@index([provider, status])

}

`

Le dashboard admin agrège : CA par provider, taux de succès, frais réels, latence moyenne. Indispensable pour les arbitrages.

Pièges du multi-passerelle

• Réconciliation comptable — chaque provider a son rythme de reversement (T+1, T+2, T+5). Faites une vue expected_settlements qui croise vos paiements et le solde bancaire attendu par jour.
• Webhook race conditions — si un même paiement est reroutés (fallback), deux webhooks peuvent arriver. La contrainte unique sur externalId + provider règle ça.
• Test en sandbox — chaque provider a son sandbox. Maintenez 3 sets de clés (.env), automatisez les fixtures.

FAQ

Q : Combien coûte la maintenance multi-passerelle ?

R : ~5 h/mois pour les mises à jour API + monitoring. Très inférieur à l'économie de frais.

Q : Comment choisir la règle de routing par défaut ?

R : Suivez vos données. Si Wave est 65 % de vos paiements, route Wave-first avec PayDunya en fallback. Si Wave est 30 %, restez 100 % PayDunya.

Q : Stripe Connect peut-il jouer le rôle d'orchestrateur ?

R : Oui pour les marketplaces internationales, non pour la plupart des PME africaines (couverture Wave/OM insuffisante). Voir notre guide Stripe Connect marketplace →.

Conclusion

Le multi-passerelle n'est pas pour tout le monde. Sous 10M FCFA/mois, l'agrégateur unique reste le bon choix (simplicité > économie marginale). Au-delà, l'architecture présentée ici est devenue notre standard chez Kolonell — elle paie son intégration en moins de 8 mois et libère un levier d'optimisation continu.