Encaissez avec un lien partageable, ou connectez moneriz à votre application depuis votre serveur.
Copiez le guide Markdown dans ChatGPT, Claude, Cursor ou votre assistant : clés, API, exemples Next.js et backend séparé, webhooks, iframe et retours vers votre SaaS. Le guide demande à l’IA de réutiliser votre authentification et votre base. Aucune clé secrète n’est incluse.
Next.js peut héberger votre interface, vos routes serveur et votre webhook dans le même projet. Avec un backend séparé, les secrets et la confirmation restent sur ce backend. Dans les deux cas, votre navigateur reçoit uniquement l’URL du checkout et le résultat vérifié par votre serveur.
Le parcours est toujours navigateur → votre serveur → API Moneriz. Le serveur vérifie la commande, crée la session et transmet uniquement les URL au navigateur. La même intégration couvre les cartes et Mobile Money ; le checkout Moneriz recueille le moyen choisi.
Les adaptateurs ci-dessous sont des points de départ à connecter à votre authentification et à votre base de données. Ils ne constituent pas une application prête à déployer : implémentez les fonctions de moneriz-app selon les contrats décrits avant de les utiliser. Ne remplacez jamais ces fonctions par des réponses fictives ou un stockage en mémoire.
| Architecture | Création de session | Réception du webhook |
|---|---|---|
| Next.js App Router, même application | src/app/api/checkout/route.ts ; appel navigateur /api/checkout | src/app/api/webhooks/moneriz/route.ts ; URL publique du site /api/webhooks/moneriz |
| Frontend et backend séparés | Route POST /api/checkout de votre backend ; appel navigateur vers votre backend | Route POST /api/webhooks/moneriz de votre backend ; URL publique du backend |
| Site exporté en HTML statique | Backend séparé ou fonction serveur indispensable | Endpoint public sur ce backend ou cette fonction |
Le navigateur envoie seulement lʼidentifiant de sa commande à votre route /api/checkout. Votre serveur ne reprend jamais son montant, sa devise, ses URL de retour ou son embedOrigin sans contrôle. Il calcule le prix en XOF depuis le catalogue et la commande enregistrés ; il vérifie que la commande appartient au payeur autorisé et reste payable.
prepareAuthorizedCheckout(request, orderId) est votre fonction applicative : vérifier session, droits, CSRF selon votre mode dʼauthentification et limites de débit ; retourner { ok: false, status: 401|403|404|409|429, code } en cas de refus, ou { ok: true, attempt: CheckoutAttempt }. Dans une transaction, créer ou relire une tentative unique par commande et mode, avec référence unique, Idempotency-Key de 16 à 128 caractères, JSON figé et session déjà connue. Une clé de mode test doit retrouver uniquement les tentatives test.
saveCheckoutSession(attempt, session) enregistre durablement le cs_… et les URL sur cette même tentative, sous contrainte unique ou mise à jour conditionnelle. Elle associe la session sans changer lʼétat métier : si un webhook a déjà confirmé la commande, ne jamais la remettre en attente. Deux clics concurrents retrouvent la même tentative, la même clé et le même JSON ; les deux écritures doivent accepter le même résultat. Effectuer lʼappel réseau hors transaction SQL, puis attendre le commit du résultat avant de répondre au navigateur. Le helper vérifie mode, montant, devise, référence et orderId reçus avant de sauvegarder la réponse réduite destinée au navigateur.
Après une coupure réseau, un timeout, une réponse JSON illisible ou incohérente, ou un commit local échoué, le helper retourne CHECKOUT_RESULT_UNKNOWN en 503. Une réponse dʼerreur JSON Moneriz, y compris 5xx, conserve son code et param ; les 401/403 liés à la clé Moneriz deviennent 503 côté payeur et ne provoquent pas sa déconnexion. Les refus dʼauthentification du payeur restent les 401/403 de prepareAuthorizedCheckout. Dans tous les cas incertains, réutiliser la tentative et son JSON exacts ; afficher une reprise explicite et temporisée, jamais un nouveau paiement. Après un refus de validation certain, corriger le JSON et enregistrer une nouvelle clé selon les règles dʼidempotence du guide. Ne régénérer ni référence ni session à chaque rendu React.
// server/moneriz-checkout.ts, ou src/lib/server/moneriz-checkout.ts dans Next.js
export type BrowserCheckout = {
id: string;
integrationMode: 'redirect' | 'iframe';
checkoutUrl: string;
embedUrl: string | null;
};
export type CheckoutAttempt = {
// Valeurs figées et enregistrées par votre serveur, jamais le corps du navigateur.
mode: 'test' | 'live';
idempotencyKey: string;
request: {
amount: number;
currency: 'XOF';
title: string;
reference: string;
integrationMode: 'redirect' | 'iframe';
embedOrigin?: string;
successUrl?: string;
cancelUrl?: string;
metadata: { orderId: string };
};
session: BrowserCheckout | null;
};
export async function createMonerizCheckout(
attempt: CheckoutAttempt,
saveSession: (session: BrowserCheckout) => Promise<void>,
): Promise<Response> {
const headers = { 'Cache-Control': 'no-store' };
if (attempt.session) return Response.json(attempt.session, { headers });
const secret = process.env.MONERIZ_SECRET_KEY;
if (!secret) return Response.json({ error: { code: 'CHECKOUT_NOT_CONFIGURED' } }, { status: 503, headers });
try {
const response = await fetch("https://api.moneriz.com/v1/checkout-sessions", {
method: 'POST',
headers: {
Authorization: 'Bearer ' + secret,
'Content-Type': 'application/json',
'Idempotency-Key': attempt.idempotencyKey,
},
body: JSON.stringify(attempt.request),
cache: 'no-store',
signal: AbortSignal.timeout(8000),
});
const result = await response.json();
if (!response.ok) {
const code = typeof result?.error?.code === 'string' ? result.error.code : 'MONERIZ_UNAVAILABLE';
const param = typeof result?.error?.param === 'string' ? result.error.param : undefined;
const retryAfter = response.headers.get('Retry-After');
return Response.json({ error: { code, param } }, {
// Un refus de la clé Moneriz concerne le marchand, pas la session du payeur.
status: [401, 403].includes(response.status) ? 503 : response.status,
headers: { ...headers, ...(retryAfter ? { 'Retry-After': retryAfter } : {}) },
});
}
if (typeof result.id !== 'string' || !result.id.startsWith('cs_') ||
result.mode !== attempt.mode ||
result.amount !== attempt.request.amount ||
result.currency !== attempt.request.currency ||
result.reference !== attempt.request.reference ||
result.metadata?.orderId !== attempt.request.metadata.orderId ||
result.integrationMode !== attempt.request.integrationMode ||
!['redirect', 'iframe'].includes(result.integrationMode) ||
typeof result.checkoutUrl !== 'string' ||
(result.embedUrl !== null && typeof result.embedUrl !== 'string') ||
(result.integrationMode === 'iframe' && !result.embedUrl)) {
throw new Error('Invalid checkout response');
}
const session: BrowserCheckout = {
id: result.id,
integrationMode: result.integrationMode,
checkoutUrl: result.checkoutUrl,
embedUrl: result.embedUrl,
};
// Le commit doit terminer avant de communiquer la session au navigateur.
await saveSession(session);
return Response.json(session, { status: 201, headers });
} catch {
// La session a peut-être été créée : reprendre la même clé et le même JSON.
return Response.json({ error: { code: 'CHECKOUT_RESULT_UNKNOWN' } }, { status: 503, headers });
}
}// src/app/api/checkout/route.ts
import { createMonerizCheckout } from '@/lib/server/moneriz-checkout';
import { prepareAuthorizedCheckout, saveCheckoutSession } from '@/lib/server/moneriz-app';
export const runtime = 'nodejs';
export async function POST(request: Request) {
let body: unknown;
try { body = await request.json(); } catch {
return Response.json({ error: { code: 'INVALID_BODY' } }, { status: 400 });
}
if (!body || typeof body !== 'object' || !('orderId' in body) || typeof body.orderId !== 'string') {
return Response.json({ error: { code: 'ORDER_ID_REQUIRED' } }, { status: 400 });
}
try {
const access = await prepareAuthorizedCheckout(request, body.orderId);
if (!access.ok) return Response.json({ error: { code: access.code } }, { status: access.status });
return await createMonerizCheckout(access.attempt, (session) =>
saveCheckoutSession(access.attempt, session));
} catch {
return Response.json({ error: { code: 'CHECKOUT_UNAVAILABLE' } }, { status: 503 });
}
}// Dans votre serveur Express, après express.json() et vos contrôles de session/CSRF.
import { createMonerizCheckout } from './moneriz-checkout.js';
import { prepareAuthorizedCheckout, saveCheckoutSession } from './moneriz-app.js';
app.post('/api/checkout', async (req, res) => {
if (typeof req.body?.orderId !== 'string') {
return res.status(400).json({ error: { code: 'ORDER_ID_REQUIRED' } });
}
try {
const access = await prepareAuthorizedCheckout(req, req.body.orderId);
if (!access.ok) return res.status(access.status).json({ error: { code: access.code } });
const response = await createMonerizCheckout(access.attempt, (session) =>
saveCheckoutSession(access.attempt, session));
response.headers.forEach((value, name) => res.setHeader(name, value));
return res.status(response.status).json(await response.json());
} catch {
return res.status(503).json({ error: { code: 'CHECKOUT_UNAVAILABLE' } });
}
});embedOrigin est lʼorigine exacte de la page frontend contenant lʼiframe, par exemple https://app.exemple.com. Lʼautoriser dans « Intégration > Sites autorisés », puis la choisir côté serveur pour cette commande. https://api.exemple.com/api/webhooks/moneriz est votre endpoint backend de notification : ce nʼest pas embedOrigin. Le webhook est aussi nécessaire en mode page de paiement hébergée.
Avec plusieurs sites, envoyer lʼembedOrigin de celui qui affiche réellement le checkout ; lʼorigine par défaut sert seulement si ce champ est omis. www, absence de www, protocole et port définissent des origines différentes. Nʼajoutez pas de chemin à une origine et ne réutilisez pas lʼembedUrl préparée pour un autre site.
En local, utiliser une clé test. HTTP localhost est accepté pour lʼiframe et les URL de retour en test ; le webhook exige toujours une URL HTTPS publique. Exposer votre route webhook via un tunnel HTTPS vers le port du serveur, puis enregistrer son URL finale dans le dashboard en mode test. Si lʼiframe est consultée via ngrok, autoriser lʼorigine HTTPS ngrok du frontend et utiliser cette origine comme embedOrigin.
En live, les origines iframe et URL de retour doivent être HTTPS. Ne pas demander un paiement réel pour vérifier le tunnel ; séparer clés, secrets webhook et données test/live. Un tunnel qui expose uniquement votre frontend statique ne peut pas recevoir un webhook de votre backend.
| Valeur | Next.js sur un seul site | Frontend et backend séparés |
|---|---|---|
| embedOrigin | https://app.exemple.com | https://app.exemple.com |
| Webhook enregistré chez Moneriz | https://app.exemple.com/api/webhooks/moneriz | https://api.exemple.com/api/webhooks/moneriz |
| successUrl / cancelUrl | https://app.exemple.com/merci ou /panier | Pages de votre frontend, pas routes webhook |
| Appel navigateur de création | POST /api/checkout avec vos contrôles de session/CSRF | POST https://api.exemple.com/api/checkout avec vos contrôles de session/CSRF et CORS |
Copier le vérificateur verifyMonerizSignature publié dans ce guide dans src/lib/server/moneriz-signature.ts (Next.js) ou server/moneriz-signature.ts (Node.js). Les deux adaptateurs importent exactement ce helper ; ne pas remplacer le corps brut par JSON.stringify(request.json()).
La route webhook est publique et réservée aux notifications signées. Excluez seulement cette route des contrôles de connexion, cookie, CSRF, redirection de login et protection de prévisualisation de lʼhébergeur. Gardez la signature et une limite de taille/débit adaptée. Moneriz nʼa pas la session de votre client : une redirection ou un 401 de login empêche toute confirmation.
parseMonerizEvent(value) est votre validation dʼenveloppe : id evt_…, type, createdAt et data selon le contrat webhook. Elle renvoie un événement validé ou null, sans effet métier. commitMonerizInbox(event) insère cet événement dans une vraie base avec contrainte unique sur event.id et statut de traitement durable ; un doublon déjà committé réussit. Elle ne résout sa promesse quʼaprès commit. En cas de panne de stockage, elle lève une erreur et la route répond 503.
Votre worker reprend les événements stockés après panne. Avant toute activation, contrôler le mode, la commande, payment.id, la référence, le montant et la devise attendus ; appliquer effet métier et marquage « traité » dans la même transaction. Pour un service externe, utiliser une clé dʼidempotence métier et un outbox durable. Ignorer sans activation les types inconnus. Une expiration ancienne ne doit pas annuler une réussite ; une réussite tardive reste possible. Répondre 2xx en moins de dix secondes seulement après stockage durable ou traitement synchrone atomique.
Le webhook peut arriver avant la sauvegarde locale du cs_… ou du pay_…. Retrouver dʼabord lʼintention de commande déjà persistée par référence et mode, vérifier ses métadonnées et rattacher le paiement de façon conditionnelle. Contrôler metadata.checkoutSessionId lorsque la session est connue. Une session peut porter plusieurs tentatives ; ne pas supposer un unique payment.id pour toute la commande et ne pas perdre un événement reçu avant le retour API.
Les événements de retrait concernent vos retraits marchands ; ils ne valident pas une commande client. La page de retour et moneriz.payment servent uniquement à actualiser lʼinterface. Pour afficher un succès, relire la commande auprès de votre serveur après le webhook ; si sa livraison est encore en cours, garder le checkout et le suivi sans créer une autre session.
// src/app/api/webhooks/moneriz/route.ts
import { verifyMonerizSignature } from '@/lib/server/moneriz-signature';
import { parseMonerizEvent, commitMonerizInbox } from '@/lib/server/moneriz-app';
export const runtime = 'nodejs';
export async function POST(request: Request) {
const secret = process.env.MONERIZ_WEBHOOK_SECRET;
if (!secret) return new Response(null, { status: 503 });
// Ne pas appeler request.json() avant cette vérification.
const rawBody = await request.text();
const signature = request.headers.get('X-Moneriz-Signature') ?? '';
if (!verifyMonerizSignature(rawBody, secret, signature)) {
return new Response(null, { status: 401 });
}
let event;
try { event = parseMonerizEvent(JSON.parse(rawBody)); } catch {
return new Response(null, { status: 400 });
}
if (!event) return new Response(null, { status: 400 });
try {
// Inbox persistante, unique sur event.id ; les doublons déjà committés réussissent.
await commitMonerizInbox(event);
return new Response(null, { status: 204 });
} catch {
// Aucun acquittement si le stockage échoue : Moneriz pourra livrer à nouveau.
return new Response(null, { status: 503 });
}
}// Monter cette route AVANT express.json(), lʼauthentification cookie et le CSRF.
import express from 'express';
import { verifyMonerizSignature } from './moneriz-signature.js';
import { parseMonerizEvent, commitMonerizInbox } from './moneriz-app.js';
app.post('/api/webhooks/moneriz', express.raw({ type: 'application/json', limit: '2mb' }), async (req, res) => {
const secret = process.env.MONERIZ_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(503);
if (!Buffer.isBuffer(req.body)) return res.sendStatus(400);
const rawBody = req.body.toString('utf8');
if (!verifyMonerizSignature(rawBody, secret, req.get('X-Moneriz-Signature') ?? '')) {
return res.sendStatus(401);
}
let event;
try { event = parseMonerizEvent(JSON.parse(rawBody)); } catch {
return res.sendStatus(400);
}
if (!event) return res.sendStatus(400);
try {
await commitMonerizInbox(event);
return res.sendStatus(204);
} catch {
return res.sendStatus(503);
}
});
app.use(express.json());
// Monter ensuite vos contrôles de session/CSRF et la route /api/checkout.Les fonctions d’authentification et de persistance des exemples doivent être raccordées à votre application. Le guide copiable précise ce contrat et les tests à effectuer avant production. Il contient aussi le vérificateur de signature utilisé par les deux adaptateurs webhook.
Dans « Intégration », choisissez une page hébergée ou une iframe, autorisez vos domaines et configurez vos retours. L’aperçu montre les moyens disponibles par pays dans le mode consulté. Les exemples techniques sont réunis dans cette documentation ; la copie depuis « Intégration » ajoute vos préférences enregistrées au même guide complet, sans secret. Votre serveur crée une session par commande avec POST /v1/checkout-sessions, une clé secrète et une Idempotency-Key conservée. Envoyez le montant, le titre, une référence unique et vos métadonnées de commande.
La réponse contient checkoutUrl pour rediriger vers moneriz, embedUrl pour l’iframe si un domaine est autorisé, et integrationMode. Le mode et les URL de retour du dashboard s’appliquent si votre serveur ne les précise pas. Aucune charge n’est lancée avant que le client choisisse son moyen dans le checkout.
Une demande iframe sans origine autorisée renvoie une erreur HTTP 400 avec error.code et error.param : EMBED_NOT_CONFIGURED, EMBED_ORIGIN_NOT_ALLOWED, EMBED_ORIGIN_INVALID ou INSECURE_URL. Une réponse 201 en mode iframe contient toujours une embedUrl. Cette URL peut être nulle en mode redirection. Le guide Markdown détaille la reprise et les clés d’idempotence.
Les webhooks reprennent votre reference et metadata.checkoutSessionId pour activer la bonne commande après vérification. Une préférence modifiée ne change pas une session existante. La route/v1/payments reste disponible pour les intégrations avancées qui choisissent explicitement le moyen de paiement.
Dans votre espace, ouvrez « Liens de paiement », choisissez un montant fixe ou libre en FCFA, le titre et le pays affiché par défaut. Choisissez un lien à usage unique pour une facture, ou réutilisable pour plusieurs clients. Copiez le lien ou téléchargez son QR code.
Pour un montant libre, le client saisit un entier de 100 à 5 000 000 FCFA avec les limites actuelles par défaut. Le serveur contrôle le montant et le conserve pour la tentative : un rechargement ne crée pas un nouveau paiement. Le nom et le pays sont obligatoires. Le téléphone est requis pour Mobile Money et facultatif pour la carte. Pour un paiement par carte, une adresse email valide est nécessaire ; Stripe la demande si elle n’a pas déjà été renseignée.
Votre client n’a pas besoin de compte moneriz : il renseigne ses coordonnées et choisit son pays et son moyen de paiement sur votre page moneriz. Stripe traite les nouveaux paiements par carte et Bictorys le Mobile Money. Le paiement confirmé apparaît dans votre historique et dans votre solde. Désactiver un lien bloque les nouveaux paiements, sans annuler ceux déjà ouverts chez le prestataire.
Ajoutez une URL de retour après paiement pour renvoyer le client vers votre SaaS ou votre site. Vous pouvez aussi la modifier avec « Configurer le retour ». La redirection intervient après confirmation du paiement ; en cas d’échec, le client peut réessayer sur moneriz. Laissez ce champ vide pour conserver la page de confirmation.
Créer un lien de paiementLa carte se saisit dans les champs sécurisés Stripe intégrés au module Moneriz. Les données de carte sont transmises directement à Stripe. Une validation bancaire 3-D Secure peut demander une navigation externe ; si elle est bloquée dans l’iframe, le module carte propose de reprendre la même demande sur la page Moneriz. Wave ou un autre opérateur peuvent aussi demander une validation externe. Les anciennes demandes carte Bictorys gardent leur parcours d’origine.
Gardez le module ouvert pendant la validation. Une URL de retour configurée reste accessible par un bouton, sans charger votre SaaS dans sa propre iframe. Le navigateur ne confirme jamais à lui seul l’encaissement.
Pour adapter la hauteur ou actualiser votre interface, l’iframe peut envoyer les événements moneriz.ready, moneriz.resize, moneriz.resume et moneriz.payment à votre domaine autorisé. Vérifiez toujours event.origin et event.source === iframe.contentWindow. Ces événements pilotent votre interface ; votre serveur vérifie le paiement, normalement par le webhook signé, avant d’activer l’accès au service.
Plusieurs sites ? Ajoutez et enregistrez chacun dans « Intégration ». Tous les sites enregistrés sont autorisés. Adaptez les exemples de ce guide à votre site. Pour chaque session, votre serveur transmet leur adresse exacte dans embedOrigin. Le site par défaut sert seulement si cette valeur est omise. Ne recopiez pas une URL d’iframe créée pour un site sur un autre : ses messages visent le site d’origine.
event.data est un objet JavaScript. Le champ s’appelle type, jamais event. Vérifiez aussi source, version et le token du checkout. Comparez les types en entier, sans recherche par suffixe.
// event.data : objet JavaScript, pas une chaîne JSON.
// Parent vers iframe, après avoir installé son écouteur message :
{ source: 'moneriz', version: 1, token: '<token>', type: 'moneriz.init' }
// Iframe vers parent :
{ source: 'moneriz', version: 1, token: '<token>', type: 'moneriz.ready' }
{ source: 'moneriz', version: 1, token: '<token>', type: 'moneriz.resize', height: 720 }
// URL de secours pour reprendre exactement la tentative dans un nouvel onglet.
{ source: 'moneriz', version: 1, token: '<token>', type: 'moneriz.resume',
resumeUrl: 'https://moneriz.com/payer/<token>?tentative=<uuid>' }
// Dès la création de la tentative, avant que le client paie : garder le QR affiché.
{
source: 'moneriz', version: 1, token: '<token>', type: 'moneriz.payment',
paymentId: 'pay_…', checkoutSessionId: 'cs_…',
status: 'pending', confirmation: 'pending'
}
// Plus tard, après confirmation serveur du paiement :
{
source: 'moneriz', version: 1, token: '<token>', type: 'moneriz.payment',
paymentId: 'pay_…',
checkoutSessionId: 'cs_…', // null pour un lien manuel
status: 'paid',
confirmation: 'confirmed'
}ready : checkout chargé et origine autorisée ; le catalogue peut encore charger.resize : hauteur entière de 320 à 4 000 pixels CSS, au montage et aux changements de hauteur.payment : tentative connue au montage, puis changement d’identifiant, de statut ou de confirmation. Sans tentative, aucun événement de paiement.resume : lien pour reprendre la tentative courante hors iframe. Le code fourni vérifie resumeUrl et met à jour le lien de secours vers cette même demande, y compris après un nouvel essai. Ne remplacez pas ce lien par une nouvelle session. Cet événement ne confirme pas le paiement.pending dès la création du QR, avant tout paiement. Gardez l’iframe et son URL inchangées : ne fermez pas la modale et ne remplacez pas le QR par un écran de confirmation.status : pending, paid, failed, expired, reversed. confirmation : pending, authorized, confirmed, review.status=paid et confirmation=confirmed, puis vérifiez la commande auprès de votre backend. Le message navigateur seul ne valide pas le paiement.izipaye.*, encore émis pour compatibilité.Le code fourni dans ce guide et son export Markdown ajuste automatiquement la hauteur, nettoie les écouteurs et propose un lien de secours vers le même paiement. Utilisez /integrer/… : /payer/… refuse les iframes. Le voile, le flou et la modale éventuels sont gérés par votre propre site.
Le module intégré est compact automatiquement. Appliquez chaque événement moneriz.resize, y compris lorsque la hauteur diminue. Évitez une hauteur maximale sur l’iframe, le zoom CSS et un grand en-tête qui répète le montant. Sur un petit écran ou avec des détails ouverts, laissez défiler la page hôte.
Un lien réutilisable accepte plusieurs paiements, à montant fixe ou libre. Pour attribuer l’achat à un utilisateur précis, votre serveur doit associer chaque commande à un paiement. Avec une session checkout Moneriz, le module prend en charge les champs carte et les actions Mobile Money. Une intégration directe de /v1/payments doit traiter nextAction ; une URL de redirection n’est pas toujours fournie.
Les logos sont stockés dans Cloudflare R2. Le pays du client peut être choisi parmi les pays et territoires du sélecteur ; les moyens Mobile Money dépendent du pays et la carte de l’autorisation accordée à votre entreprise et de la disponibilité du service dans le mode choisi. La carte est désactivée par défaut : demandez son activation dans Paramètres → Carte bancaire. Un lien réutilisable ne déclenche aucun renouvellement automatique d’abonnement.
Personnaliser mon checkoutUne seule clé suffit pour le checkout hébergé et Liveframe. Créez votre clé dans « Clés & webhook », puis enregistrez-la dans MONERIZ_SECRET_KEY sur votre serveur. Votre frontend reçoit l’URL de la session, sans clé API.
izp_test_sk_… pour vos tests, izp_live_sk_… pour la production. Elle crée les sessions, consulte les paiements et lit aussi le catalogue des moyens de paiement.izp_test_pk_… ou izp_live_pk_… permet uniquement de lire GET /v1/payment-methods depuis le navigateur pour une interface personnalisée. Le checkout Moneriz charge déjà ce catalogue : vous n’avez pas besoin de cette clé pour votre intégration standard. Elle reste copiable dans votre espace.
Plusieurs paires nommées peuvent coexister. Révoquer une paire désactive ses deux clés. Gardez les clés et les endpoints de webhook séparés pour le test et la production.
Votre serveur crée une session checkout Moneriz. Le montant vient de votre catalogue : 5000 représente 5 000 FCFA. Conservez la référence et la clé d’idempotence sur votre commande. Remplacez les URL d’exemple par celles de votre site.
curl 'https://api.moneriz.com/v1/checkout-sessions' \
-H "Authorization: Bearer $MONERIZ_SECRET_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: commande-2026-001' \
-d '{
"amount": 5000,
"currency": "XOF",
"title": "Accès Pro",
"country": "SN",
"reference": "commande-2026-001",
"successUrl": "https://exemple.sn/merci",
"cancelUrl": "https://exemple.sn/panier"
}'Une réponse 201 fournit id, status, checkoutUrl, embedUrl et integrationMode. Elle ne crée aucun débit. Le parcours enregistré dans « Intégration » s’applique : pour redirect, ouvrez checkoutUrl ; pour iframe, montez embedUrl avec le code de ce guide. Le client choisit ensuite son moyen de paiement.
Les coordonnées et les éventuels codes Mobile Money sont demandés dans le checkout. N’envoyez ni numéro de carte, ni cryptogramme, ni OTP dans la création de session. Après une interruption réseau, reprenez cette commande avec la même clé et le même contenu.
Pour une interface avancée, POST /v1/payments exige un paymentType explicite et les coordonnées requises par le catalogue. La carte renvoie une action Stripe à intégrer, avec checkoutUrl=null. Consultez la référence carte Stripe. Les sessions checkout prennent déjà en charge cette interface. Dans tous les cas, activez l’accès après le webhook signé, même si le client ferme son navigateur.
La redirection du navigateur ne prouve pas le paiement. Activez votre service après réception de payment.succeeded et vérification de la signature X-Moneriz-Signature. Le format est t=<horodatage en ms>,v1=<hex> : HMAC-SHA256 du texte horodatage.corpsBrut, avec le secret de votre endpoint. Contrôlez la fraîcheur de l’horodatage, comparez la signature en temps constant et dédoublonnez avec l’identifiant de l’événement.
Dans Clés & webhook, ajoutez l’URL HTTPS de votre serveur et enregistrez le secret affiché à la création. Traitez aussi les échecs, expirations et annulations de crédit selon votre parcours. Enregistrez durablement chaque événement avant de répondre 2xx, en moins de dix secondes. Déduplication et activation doivent être atomiques ou reprises depuis une file persistante.
Chaque paiement confirmé retient 5 % de commission moneriz, arrondis à l’entier inférieur en FCFA. Sur 10 000 FCFA, 9 500 FCFA rejoignent le solde en attente. Ils deviennent disponibles après 72 heures en Mobile Money ou 14 jours par carte, à compter de la confirmation serveur de cette vente. Un webhook dupliqué ne crédite pas le wallet une seconde fois.
Le marchand demande ensuite un retrait vers son compte de réception. Les fonds sont réservés ; le versement est déclenché après validation par l’équipe Moneriz. Une seule demande peut être en cours par organisation et mode. Vérification d’identité, minimum, plafond et contrôles de sécurité peuvent s’appliquer. Le délai du transfert dépend du prestataire ; il ne se confond pas avec les délais de disponibilité des ventes. Les opérations et soldes de test restent séparés de la production.
Informez vos clients des données collectées et de leurs usages. Ne placez pas de secrets, de documents d’identité ni de données de carte dans les références et métadonnées. Une relance WhatsApp se prépare manuellement ; le numéro collecté ne constitue pas une autorisation de prospection.
La politique de confidentialité décrit les destinataires et les droits. Consultez aussi les conditions d’utilisation. Le contrat avec le marchand doit préciser les responsabilités de chacun pour le traitement des données.
Idempotency-Key pour rejouer une même demande avec le même contenu.availability vaut unknown n’est pas confirmé disponible. Le catalogue dépend du pays et du compte.MODE_NOT_CONFIGURED signale une configuration serveur manquante.Consultez la référence API complète : les endpoints, leurs champs, la pagination, les quotas, les erreurs et la recette avant production. Elle est aussi incluse dans le Markdown copiable.
Créer mon compte