VidiPay
VidiPay
Plateforme de paiement pour développeurs : API REST, sandbox, tokens, callbacks Mobile Money et Visa.
Vidipay est un agrégateur de paiement virtuel : une plateforme complète pour apprendre et intégrer Mobile Money, cartes Visa, retraits, remboursements et notifications asynchrones — avec la même rigueur qu'un agrégateur professionnel, sans risque financier en mode test. La documentation technique détaille chaque endpoint ; cette page explique le système dans sa profondeur.
Vidipay s'adresse aux étudiants, jeunes développeurs et équipes produit qui veulent comprendre comment fonctionne un paiement en ligne en Afrique centrale et au-delà, sans attendre des semaines d'onboarding marchand ni risquer de l'argent réel pendant les tests.
À l'inscription, chaque marchand reçoit immédiatement un code marchand, un token API Bearer (long, sécurisé), des identifiants de test uniques (numéros Mobile Money, carte Visa test) et tokens Vidipay pour expérimenter.
L'objectif n'est pas de remplacer un agrégateur bancaire ou Mobile Money réel, mais de vous permettre de maîtriser le flux complet — initiation, validation, journalisation, callback, vérification — avant de brancher un prestataire en production.
Vidipay suit une architecture en couches typique des agrégateurs de paiement : votre application (marchand) communique avec une API REST ; le cœur Vidipay valide, enregistre et orchestre ; les notifications repartent vers vos serveurs.
| Couche | Rôle |
|---|---|
| API REST | Points d'entrée HTTP : authentification Bearer, validation des champs, codes d'erreur normalisés (errorCode). |
| Moteur métier | Traitement des dépôts (Mobile Money / Visa), retraits, remboursements, calcul des soldes par devise. |
| Journal (ledger) | Chaque requête API acceptée ou rejetée est persistée avec statut, montants, références et historique tokens. |
| Callbacks | Notifications HTTP POST asynchrones vers l'URL que vous fournissez (callbackUrl), avec payload minimal si l'URL est enregistrée. |
| Portail carte | Formulaire hébergé Vidipay pour saisie carte Visa en production — les données sensibles ne transitent jamais par votre backend. |
| Dashboard marchand | Interface web : identifiants, journaux, callbacks, facturation, documentation. |
Vidipay expose cinq familles d'opérations, calquées sur les agrégateurs professionnels :
| Service | Méthode | Rôle | Forfait min. |
|---|---|---|---|
paymentService |
POST | Initier un dépôt Mobile Money (type=1) ou Visa (type=2) |
Free (MM) / Premier (Visa) |
payoutService |
POST | Retrait vers un numéro bénéficiaire — débit du solde marchand | Premier |
refundService |
POST | Rembourser un dépôt réussi identifié par référence / orderNumber | Pro / Premier |
balance |
GET | Soldes retraitables par devise (CDF, USD) — gratuit | Free |
check/{orderNumber} |
GET | Vérifier le statut d'une transaction — gratuit | Free |
Chaque service partage les mêmes principes : header Authorization: Bearer vp_live_...,
champ merchant obligatoire, reference unique côté marchand,
réponses JSON avec code (0 = succès) et orderNumber en cas de succès.
POST paymentService, authentifie le Bearer token et associe la requête au marchand.243XXXXXXXXX), devise (CDF/USD), URL callback HTTPS, référence non dupliquée, solde tokens suffisant.ApiDeposit avec statut initial, déduction d'1 token Vidipay si accepté.paymentUrl vers le portail payeur.orderNumber renvoyé au marchand.callbackUrl avec statut final.
Les retraits (payoutService) et remboursements (refundService) suivent
une logique analogue : validation → vérification du solde → enregistrement → callback.
| Mode | Déclencheur | Comportement |
|---|---|---|
| Test Mobile Money | phone = numéro test (Espace API) |
Paiement simulé, callback auto, aucun débit réel |
| Test Visa | type=2 + card = carte test |
Même simulation — forfait Premier requis |
| Visa portail | type=2 sans card |
Réponse paymentUrl — le payeur saisit sa carte sur Vidipay |
| Live Mobile Money | Numéro réel valide | Flux réel (selon configuration plateforme) |
| Sandbox global | PAIEMENT_MODE=sandbox |
Tous les numéros simulés — utile en développement |
Le champ payment_mode (test / live) est enregistré
dans chaque ApiDeposit pour traçabilité dans le journal marchand.
AUTH_001.VAL_017) ; collecte via portail hébergé.status, reference, orderNumber) pour limiter l'exposition.errorCode ; le détail est dans la documentation, pas dans la réponse HTTP.BIZ_005 si le forfait ne le permet pas.Chaque marchand dispose d'un solde retraitable par devise (CDF et USD séparés). Le calcul est déterministe :
Solde(devise) = Σ dépôts réussis − Σ retraits − Σ remboursements (en cours ou réussis)
Un retrait en CDF ne peut pas consommer un solde USD (BIZ_004 si insuffisant).
L'endpoint GET balance expose ces montants gratuitement avant un payoutService.
Les tokens Vidipay (quota API) sont distincts du solde marchand : ils mesurent combien de requêtes payantes vous pouvez encore envoyer, pas combien d'argent virtuel vous avez encaissé.
Les agrégateurs ne répondent pas toujours de façon synchrone : le paiement peut être confirmé
quelques secondes plus tard. Vidipay reproduit ce comportement en envoyant un POST JSON
sur votre callbackUrl.
| Situation | Payload |
|---|---|
| URL enregistrée dans Callbacks | Minimal : status, reference, orderNumber (+ champs refund si applicable) |
| URL non enregistrée | Complet : inclut code, provider_reference, etc. |
Bonne pratique : enregistrez chaque environnement (dev, staging, prod) avec une URL dédiée,
répondez HTTP 200, et traitez les notifications de façon idempotente
(même reference = même logique métier).
Quatre niveaux — votre forfait actuel : — (connectez-vous).
| Forfait | Tokens | Accès |
|---|---|---|
| Free | à l'inscription | Dépôt Mobile Money + callback dépôt + check + balance |
| Standard | Pack 250 | Comme Free, avec renouvellement tokens |
| Pro | Packs 250 / 500 | Standard + refundService + callbacks remboursement |
| Premier | Pack 500 | Tout : Visa (type=2), payout, refund, tous callbacks |
| Concept | Description |
|---|---|
| Tokens Vidipay | Crédits consommés : 1 token par paymentService, payoutService ou refundService accepté. Pas de déduction sur erreur de validation. |
Token API (vp_live_...) |
Clé d'authentification Bearer — ne se consomme pas, se régénère depuis l'Espace API. |
| check / balance | Gratuits — ne consomment aucun token Vidipay. |
Solde affiché en permanence : disponible après connexion dans le dashboard.
Chaque opération API alimente des modèles persistants consultables dans le dashboard :
order_number.
Cette traçabilité permet d'auditer une intégration, de déboguer un callback manquant
et de corréler une reference marchand avec un orderNumber Vidipay.
Le dashboard est le panneau de contrôle du marchand, pas seulement un journal :
| Page | Fonction |
|---|---|
| Dashboard | Vue d'ensemble tokens, dépôts, montants CDF/USD |
| Espace API | Identifiants, URLs, exemples multi-langages |
| Dépôts / Retraits / Remboursements | Journaux filtrables par date, devise, téléphone |
| Callbacks | Gestion des URLs de notification |
| Facturation | Forfaits, achat de packs tokens |
| Documentation | Référence technique des endpoints |
| À propos | Cette page — vision et architecture du système |
En intégrant Vidipay, vous maîtrisez des compétences directement transférables vers un agrégateur réel :
Votre code d'intégration reste valide : en production réelle, vous changez principalement les URLs et les identifiants, pas la structure des requêtes.
Accéder à la documentation technique →| Agrégateur réel (typique) | Vidipay |
|---|---|
| Onboarding KYC, délais, sandbox sur demande | Compte et API immédiats à l'inscription |
| Documentation fragmentée, plusieurs environnements | Espace API, docs, journaux et callbacks au même endroit |
| Risque de tests avec argent réel | Numéros et cartes test dédiés — simulation automatique |
| Erreurs opaques en production | Catalogue errorCode documenté (VAL_, BIZ_, AUTH_, CHK_) |
| Frais et contrats marchands | Packs tokens transparents — apprentissage à faible coût |
Vidipay est la phase d'apprentissage : une fois votre flux validé ici, vous êtes prêt à négocier et brancher un prestataire Mobile Money ou carte réel avec confiance dans votre architecture.