Free Money Sénégal : intégration API + considérations techniques 2026

Free Money est le wallet de l'opérateur Free Sénégal (ex-Tigo). Plus jeune que Wave et OM, mais avec une base utilisateur fidèle (~3M abonnés Free SN). L'intégrer en 4ème option e-commerce capture les 8-12 % de paniers que vous perdez sinon.

TL;DR

- Free Money API : disponible via PayDunya/CinetPay (recommandé) OU intégration directe via partenaire Free.

- Frais : 2.5 % (via PayDunya) ou 1.8-2.2 % (négocié direct).

- Volume Free Money 2026 : ~3M abonnés actifs au Sénégal, ~12 % de market share mobile money.

Pourquoi intégrer Free Money

Cas terrain : une boutique mode jeune adulte à Dakar, audience 18-30 ans :

• 51 % paient Wave
• 28 % paient Orange Money
• 11 % paient Free Money
• 10 % paient carte ou cash

Si vous ne proposez pas Free Money, ces 11 % :

• 6 % se débrouillent avec un autre wallet (frustration)
• 5 % abandonnent le panier

À volume 100M FCFA/mois, c'est 5M FCFA/mois perdus.

Option 1 — Via PayDunya (recommandée)

PayDunya supporte Free Money depuis 2023. Le mode checkout standard inclut Free Money sans config supplémentaire.

`ts

// Voir tutoriel PayDunya complet pour invoice basique

const invoice = await createPayDunyaInvoice({

orderId: 'ord_123',

totalXof: 8500,

items: [...],

});

// La page hosted PayDunya proposera Wave + OM + Free Money + carte

`

Avantages :

• Pas d'intégration séparée
• Webhook IPN unifié
• Reversement unique sur votre IBAN
• Frais ~2.5 %

Inconvénients :

• Marge agrégateur 0.5-1 % vs intégration directe
• Pas de possibilité d'UI custom (page hosted)

Option 2 — Intégration directe via partenaire Free

Free Sénégal a ouvert un programme partenaires entreprises en 2024. Conditions :

• KYC entreprise complet (RCCM, NINEA, RIB)
• Volume mensuel attendu > 5M FCFA
• Audit technique Free Sénégal
• Délai onboarding : 4-8 semaines

API exposée :

• /auth/token — OAuth2
• /payment/initiate — démarrer un paiement
• /payment/status/{id} — vérifier statut
• Webhook signé (HMAC-SHA256)

`ts

// lib/free-money.ts

const FM_BASE = 'https://api.free.sn/v1';

async function getToken() {

const auth = Buffer.from(${process.env.FM_CLIENT_ID}:${process.env.FM_CLIENT_SECRET}).toString('base64');

const res = await fetch(${FM_BASE}/auth/token, {

method: 'POST',

headers: { 'Authorization': Basic ${auth}, 'Content-Type': 'application/x-www-form-urlencoded' },

body: 'grant_type=client_credentials&scope=payment',

});

return (await res.json()).access_token;

}

export async function initFreeMoneyPayment(orderId: string, amountXof: number, payerMsisdn: string) {

const token = await getToken();

const res = await fetch(${FM_BASE}/payment/initiate, {

method: 'POST',

headers: { 'Authorization': Bearer ${token}, 'Content-Type': 'application/json' },

body: JSON.stringify({

external_id: orderId,

amount: amountXof,

currency: 'XOF',

payer_msisdn: payerMsisdn, // format E.164 +221XXXXXXXX

callback_url: 'https://kolonell.com/api/webhooks/free-money',

description: Commande ${orderId},

}),

});

const data = await res.json();

return data; // { transaction_id, status: 'PENDING', otp_required: true/false }

}

`

Workflow utilisateur Free Money

`

[Checkout] → [Saisir n° Free Money] → init API → SMS OTP envoyé client

↓

[Client tape OTP]

↓

[Validation Free → notif IPN]

↓

[Commande passe en "paid"]

`

Délai total : 30-90 secondes.

Webhook Free Money

`ts

// app/api/webhooks/free-money/route.ts

import crypto from 'crypto';

export async function POST(req: NextRequest) {

const body = await req.text();

const sig = req.headers.get('x-free-signature') || '';

const expected = crypto.createHmac('sha256', process.env.FM_WEBHOOK_SECRET!)

.update(body).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {

return NextResponse.json({ error: 'invalid_signature' }, { status: 401 });

}

const event = JSON.parse(body);

// event: { transaction_id, status, external_id, amount, ... }

// Idempotence

const existing = await prisma.paymentEvent.findUnique({

where: { externalId: event.transaction_id }

});

if (existing) return NextResponse.json({ ok: true, deduped: true });

if (event.status === 'COMPLETED') {

await prisma.$transaction([

prisma.paymentEvent.create({ data: { ... } }),

prisma.order.update({ where: { id: event.external_id }, data: { status: 'paid' } }),

]);

}

return NextResponse.json({ ok: true });

}

`

Pièges fréquents

• Numéro saisi doit être Free — vérifier le préfixe (771-779-... pas tous, voir liste Free SN officielle).
• OTP timeout — l'utilisateur a 90 secondes pour saisir l'OTP. Au-delà, transaction expire.
• Frais utilisateur côté Free — le payeur peut être facturé 1 % par Free, à clarifier dans votre UX.
• Reversement bancaire UEMOA — comme OM, T+1 ouvré.

Comparatif Free Money vs concurrents (Sénégal)

FAQ

Q : Free Money fonctionne hors Sénégal ?

R : Non, c'est un wallet local Sénégal. Pour la Côte d'Ivoire, équivalent = Moov Money. Pour le Mali = Moov / Sotelma Mobile Money.

Q : Faut-il un compte Free Sénégal côté commerçant ?

R : Oui pour le mode direct. Compte Pro Free + RIB validé. Pas nécessaire si vous passez par PayDunya.

Q : OAuth tokens à renouveler ?

R : Oui, expiration ~1h. Cache Redis 50 min, regénérer au-delà.

Conclusion

Free Money est le 4ème wallet sénégalais à proposer absolument quand vous visez l'audience jeune. Via PayDunya, l'intégration est gratuite et instantanée. Direct avec Free Sénégal, économie ~0.5-1 % de frais mais 4-8 semaines d'onboarding. Les deux options sont valides, le choix dépend de votre volume.