API paiement mobile RDC pour développeurs

1. Parcours marchand

1

Créer un compte — À l'inscription, Vidipay génère automatiquement le code marchand, le token API et le numéro de test.

2

Acheter des tokens — Chaque appel paymentService accepté consomme 1 token. Achetez des packs sur /achat-token/.

3

Intégrer l'API — Depuis Espace API, copiez l'URL, le Bearer token et le code marchand.

4

Envoyer paymentService — POST avec montant, téléphone, reference unique et callbackUrl.

5

Recevoir le callback — Vidipay POST sur votre URL avec code, reference et orderNumber.

6

Suivre les dépôts — Consultez Dépôts API et le Dashboard.

2. Identifiants & URLs

Identifiants uniques, générés une seule fois à l'inscription — visibles dans Espace API. Votre code marchand : VOTRE_CODE.

Élément	Usage
Code marchand	Champ `merchant` dans chaque requête
Token API (Bearer)	Header `Authorization: Bearer vp_live_...`
Numéro test paiement	`243900XXXXXX` — payeur Mobile Money (`type=1`)
Numéro compte dépôt	Généré à l'inscription — solde crédité ; bénéficiaire `payoutService`
Numéro test remboursement	`243902XXXXXX` — payeur dépôt + `refundService`
Carte Visa test	`411111XXXXXXXXXX` — `type=2` (Premier)
URL paiement	https://vidipay.tech/api/rest/v1/paymentService
URL retrait	https://vidipay.tech/api/rest/v1/payoutService
URL remboursement	https://vidipay.tech/api/rest/v1/refundService (Pro / Premier)
URL soldes	https://vidipay.tech/api/rest/v1/balance (gratuit)
URL vérification	https://vidipay.tech/api/rest/v1/check/{orderNumber} (gratuit)

3. API paymentService

Endpoint

POST https://vidipay.tech/api/rest/v1/paymentService
Content-Type: application/json
Authorization: Bearer vp_live_VOTRE_TOKEN

Corps de la requête

Champ	Obligatoire	Description
`merchant`	Oui	Code marchand (Espace API)
`type`	Oui	`1` = Mobile Money, `2` = Visa carte
`reference`	Oui	Référence unique côté marchand (max 64)
`phone`	Si type=1	`243XXXXXXXXX` — numéro test ou réel
`card`	Si type=2 test	Carte Visa test (Espace API). Production : ne pas envoyer — utiliser `paymentUrl`
`amount`	Oui	Montant > 0
`currency`	Oui	`CDF` ou `USD`
`callbackUrl`	Oui	URL HTTPS de retour (callback marchand)

Exemple

{
  "merchant": "VOTRE_CODE",
  "type": "1",
  "phone": "243900XXXXXX",
  "reference": "MM0000159",
  "amount": "100",
  "currency": "CDF",
  "callbackUrl": "https://votre-app.com/callback"
}

Voir aussi § 3b Paiement Visa (type=2) pour carte test et portail payeur.

Réponse succès (HTTP 200)

{
  "code": "0",
  "message": "Transaction test envoyée avec succès. Callback simulé.",
  "orderNumber": "abc123xyz..."
}

Réponse erreur (HTTP 400 / 401 / 404)

L'API renvoie un code d'erreur (errorCode), pas un message détaillé. Consultez la section Codes d'erreur API pour le détail de chaque code.

{
  "code": "1",
  "errorCode": "BIZ_002"
}

Plusieurs erreurs de validation en une requête :

{
  "code": "1",
  "errorCode": "VAL_001",
  "errorCodes": ["VAL_001", "VAL_007"]
}

Règles importantes

1 token Vidipay déduit par requête acceptée (pas sur erreurs de validation)
Numéro de test → paiement simulé, callback auto après ~3 s
Carte Visa test (type=2 + card) → même comportement test
Carte réelle → rediriger vers paymentUrl (portail Vidipay) — ne jamais envoyer la vraie carte dans l'API
Autre numéro valide → paiement Mobile Money réel
reference doit être unique par marchand

3b. Paiement Visa — paymentService (`type=2`)

Forfait Premier requis. Sans Premier, type=2 renvoie BIZ_005. Même endpoint paymentService que le Mobile Money, avec "type": "2". Format carte Visa internationale (16 chiffres, commence par 4, valide Luhn). Le remboursement utilise le même refundService (champ card ou depositOrderNumber).

Deux modes

Mode	Requête API	Comportement
Test	`type=2` + `card` = carte test (Espace API)	Succès immédiat + callback simulé (~3 s) — comme le numéro Mobile Money test
Production	`type=2` sans `card`	Réponse `paymentUrl` → rediriger le payeur vers le portail Vidipay pour saisir sa vraie carte

Carte Visa test : 411111XXXXXXXXXX — visible dans Espace API. Ne transmettez jamais la vraie carte dans l'API : c'est le portail https://vidipay.tech/pay/card/ORDER_NUMBER/ qui collecte les données du payeur.

Champs requête (type=2)

Champ	Test	Production	Description
`merchant`	Oui	Oui	Code marchand
`type`	Oui	Oui	`"2"` = Visa
`reference`	Oui	Oui	Référence unique
`amount` / `currency`	Oui	Oui	Montant et devise
`callbackUrl`	Oui	Oui	Notification marchand après paiement
`card`	Oui	Non	Carte test uniquement — interdit en prod (`VAL_017`)

Portail payeur (production)

Après POST paymentService sans card, redirigez le client vers paymentUrl. Le formulaire Vidipay demande : titulaire, numéro Visa, expiration, CVV. Ces données ne transitent pas par votre backend.

Exemples de requête — multi-langages

cURL — dépôt test

Réponses

Test :

{
  "code": "0",
  "message": "Transaction test envoyée avec succès. Callback simulé.",
  "orderNumber": "..."
}

Portail (live) :

{
  "code": "0",
  "message": "Redirigez le client vers le portail Vidipay pour saisir sa carte.",
  "orderNumber": "...",
  "paymentUrl": "https://vidipay.tech/pay/card/ORDER_NUMBER/",
  "requiresPortal": true
}

Erreurs spécifiques carte

errorCode	Signification
`BIZ_005`	Forfait Premier requis pour Visa (`type=2`)
`VAL_016`	Numéro de carte invalide (Visa / Luhn)
`VAL_017`	Carte réelle envoyée dans l'API — utilisez le portail
`VAL_003`	`type` doit être `1` ou `2`

4. API payoutService

Permet d'effectuer un retrait (transfert sortant) vers un numéro Mobile Money bénéficiaire. Vidipay vérifie d'abord votre solde global (somme des dépôts réussis moins les retraits déjà effectués), puis déduit 1 token API et initie le transfert virtuel.

Endpoint

POST https://vidipay.tech/api/rest/v1/payoutService
Content-Type: application/json
Authorization: Bearer vp_live_VOTRE_TOKEN

Corps de la requête

Champ	Obligatoire	Description
`merchant`	Oui	Votre code marchand (Espace API)
`reference`	Oui	Référence unique du retrait (max 64 car.)
`phone`	Oui	Numéro bénéficiaire — format `243XXXXXXXXX`
`amount`	Oui	Montant > 0
`currency`	Oui	`CDF` ou `USD`
`callbackUrl`	Oui	URL de notification après traitement

Exemple

{
  "merchant": "VOTRE_CODE",
  "reference": "PO0000042",
  "phone": "243901000003",
  "amount": "50",
  "currency": "CDF",
  "callbackUrl": "https://votre-app.com/callback-payout"
}

Exemple de requête — multi-langages

Exemple de requête API avec différents langages de programmation. Remplacez VOTRE_TOKEN_API par votre token vp_live_... (Espace API).

cURL

Réponse succès (HTTP 200)

{
  "code": "0",
  "message": "Retrait initié. Transfert vers le numéro bénéficiaire effectué.",
  "orderNumber": "abc123..."
}

Erreurs spécifiques retrait

errorCode	Signification
`BIZ_002`	Solde tokens API insuffisant (1 token requis)
`BIZ_004`	Solde insuffisant dans la devise demandée (CDF ou USD)
`BIZ_005`	Forfait Premier requis (payoutService ou Visa `type=2`)
`BIZ_001`	Référence déjà utilisée
`VAL_014`	Champs obligatoires manquants

En cas de BIZ_004, la réponse inclut vos soldes par devise :

{
  "code": "1",
  "errorCode": "BIZ_004",
  "currency": "CDF",
  "requestedAmount": 50,
  "availableBalance": 0,
  "balances": { "CDF": 0, "USD": 10000 }
}

Consultez vos soldes avant un retrait : § 4c API balance — GET https://vidipay.tech/api/rest/v1/balance (gratuit, Bearer token).

Règles

Le solde est calculé par devise : dépôts réussis (test_ok, reussi) − retraits − remboursements en cours ou réussis
Un retrait en USD ne peut pas utiliser un solde CDF (et inversement)
Numéro compte (receive_phone) → retrait test dans payoutService + callback après ~3 s
Journal visible dans Retraits API
Enregistrez l'URL callback dans Callbacks (section retraits)

4b. API refundService

Rembourse un dépôt réussi déjà enregistré. Vidipay recherche dans la base un ApiDeposit dont les champs correspondent exactement à la requête (merchant, reference, phone, amount, currency) avec statut test_ok ou reussi. Avec depositOrderNumber, le dépôt est ciblé par son orderNumber (réponse check / paymentService) puis les autres champs sont vérifiés. Sinon : BIZ_006 (transaction introuvable).

Forfait requis : Pro ou Premier. Consomme 1 token si accepté.

Numéro test remboursement (Espace API) : 243902XXXXXX — doit être identique au phone du dépôt réussi. Journal : Remboursements API.

Enregistrez l'URL callback dans Callbacks (section remboursements) pour un payload minimal
Callback simulé vers le payeur après ~3 s en mode test

Endpoint

POST https://vidipay.tech/api/rest/v1/refundService
Content-Type: application/json
Authorization: Bearer vp_live_VOTRE_TOKEN

Corps de la requête

Champ	Obligatoire	Description
`merchant`	Oui	Code marchand
`reference`	Oui	Référence du dépôt d'origine (paymentService)
`depositOrderNumber`	Non	`orderNumber` du dépôt réussi (check API) — recherche plus précise en BDD
`phone`	Oui si Mobile Money	Même numéro payeur que le dépôt
`card`	Oui si Visa	Même carte test que le dépôt, ou `depositOrderNumber`
`amount`	Oui	Même montant que le dépôt
`currency`	Oui	`CDF` ou `USD` — identique au dépôt
`callbackUrl`	Oui	URL de notification remboursement
`refundReference`	Non	ID unique de cette opération de remboursement (sinon généré)

Exemple

{
  "merchant": "VOTRE_CODE",
  "reference": "TEST-372AB382",
  "depositOrderNumber": "aSa1eILN98MAjVd31782336431",
  "phone": "243902XXXXXX",
  "amount": "10000",
  "currency": "CDF",
  "callbackUrl": "https://votre-app.com/callback-refund",
  "refundReference": "RF0000042"
}

Exemple de requête — multi-langages

Exemple de requête refundService avec différents langages de programmation. Remplacez VOTRE_TOKEN_API par votre token vp_live_... (Espace API). Les champs doivent correspondre au dépôt réussi (référence, montant, devise, payeur).

cURL

Réponse succès (HTTP 200)

{
  "code": "0",
  "message": "Remboursement initié. Callback simulé vers le payeur.",
  "orderNumber": "abc123...",
  "depositOrderNumber": "order_du_depot_origine"
}

Erreurs spécifiques

errorCode	Signification
`BIZ_006`	Aucun dépôt réussi correspondant — transaction introuvable
`BIZ_007`	Ce dépôt a déjà été remboursé
`BIZ_004`	Solde marchand insuffisant dans la devise
`BIZ_005`	Forfait insuffisant (Pro/Premier pour refund mobile, Premier pour Visa)
`VAL_015`	Champs obligatoires manquants

Callback remboursement

Enregistrez l'URL dans Callbacks → remboursements (forfait Pro / Premier). Payload minimal si l'URL est enregistrée :

{
  "status": "0",
  "reference": "RF0000042",
  "depositReference": "TEST-372AB382",
  "orderNumber": "...",
  "depositOrderNumber": "aSa1eILN98MAjVd31782336431"
}

Sinon payload complet avec code et provider_reference.

4c. API balance — soldes retraitables

Retourne vos soldes disponibles pour les retraits, par devise (CDF et USD). Utile avant un payoutService pour éviter BIZ_004 (solde insuffisant).

Gratuit — ne consomme pas de token API.

Endpoint

GET https://vidipay.tech/api/rest/v1/balance
Authorization: Bearer vp_live_VOTRE_TOKEN

Aucun corps de requête. Seul le header Authorization est requis.

Réponse succès (HTTP 200)

{
  "code": "0",
  "message": "Soldes retraitables",
  "balances": {
    "CDF": 150000,
    "USD": 250.5
  }
}

Le solde par devise = dépôts réussis − retraits − remboursements (en cours ou réussis). Un retrait en CDF ne peut pas utiliser le solde USD.

Exemple de requête — multi-langages

Exemple GET balance avec différents langages. Remplacez VOTRE_TOKEN_API par votre token vp_live_... (Espace API).

cURL

5. API check transaction

Endpoint

GET https://vidipay.tech/api/rest/v1/check/{orderNumber}
Authorization: Bearer vp_live_VOTRE_TOKEN

Gratuit — ne consomme pas de token.

Réponse succès

{
  "code": "0",
  "message": "Une transaction trouvée",
  "transaction": {
    "orderNumber": "abc123...",
    "reference": "MM0000159",
    "amount": "100",
    "amountCustomer": "100",
    "currency": "CDF",
    "createdAt": "16/06/2026 14:30:00",
    "status": "0"
  }
}

status : 0 = réussi, 1 = échoué ou en attente.

Réponse erreur (HTTP 404)

{
  "code": "1",
  "errorCode": "CHK_001",
  "transaction": null
}

6. Callbacks marchand

Après traitement du dépôt, du retrait ou du remboursement, Vidipay envoie un POST JSON à votre callbackUrl. Enregistrez vos URLs dans Callbacks (dépôts, retraits et remboursements) pour recevoir un payload minimal.

Callback autonome — phase 1 (sans opérateur Mobile Money réel)

Vidipay ne contacte pas encore directement Vodacom, Airtel ou Orange. Le callback marchand fonctionne malgré tout de façon autonome, comme dans un agrégateur complet : dès qu'un dépôt est accepté, Vidipay notifie votre callbackUrl sans action de votre part.

Situation	Comportement	Callback marchand
Numéro de test (Espace API)	Paiement simulé immédiatement	POST automatique sur `callbackUrl` après ~3 secondes
`PAIEMENT_MODE=sandbox` + `DEBUG=True`	Tout numéro simulé (pas d'appel opérateur)	Idem — callback automatique
Numéro réel + mode production	Passage par pawaPay / Mobile Money	Callback après confirmation opérateur (phase ultérieure)

En phase 1, utilisez votre numéro de test et une URL (webhook.site ou endpoint enregistré dans Callback dépôts) : le flux complet paymentService → traitement → callbackUrl se enchaîne tout seul, comme en production, sans vrai débit Mobile Money.

Comment configurer un callback dépôt

1

Ouvrir Callback dépôts — Menu latéral → Callback (/callbacks/).

2

Préparer votre URL — En production : l'endpoint HTTPS de votre serveur. En test local : copiez une URL unique sur https://webhook.site (onglet « Your unique URL »).

3

Ajouter l'URL — Collez l'URL dans le formulaire, puis cliquez Ajouter. Vous pouvez aussi renseigner un libellé optionnel (voir ci-dessous).

4

Utiliser la même URL dans l'API — Lors du POST paymentService, le champ callbackUrl doit être identique à l'URL enregistrée (même domaine et chemin ; une barre / finale en plus ou en moins est ignorée).

5

Recevoir la notification — Après paiement (ou simulation avec le numéro de test), Vidipay POST sur votre URL. Vérifiez aussi la colonne Callback dans Dépôts API.

Libellé optionnel — à quoi ça sert ?

Le libellé est un nom d'affichage pour vous uniquement. Il n'est pas envoyé dans le callback et n'influence pas le matching avec callbackUrl. Seule l'URL compte techniquement.

Il devient utile lorsque vous enregistrez plusieurs URLs : le libellé permet de les distinguer dans la liste sans relire chaque adresse complète.

Libellé (exemple)	URL (exemple)	Usage
Production	https://api.monapp.com/paiement/callback	Serveur live
Test webhook.site	https://webhook.site/abc-123	Tests locaux
Staging	https://staging.monapp.com/callback	Pré-production

Si vous n'avez qu'une seule URL, vous pouvez laisser le libellé vide — la colonne affichera « — » dans le tableau.

Exemple complet (test avec webhook.site)

# 1. URL copiée sur webhook.site, ajoutée dans Callback dépôts :
https://webhook.site/abc-123-def

# 2. Requête paymentService (même callbackUrl) :
POST https://vidipay.tech/api/rest/v1/paymentService
Authorization: Bearer vp_live_...
Content-Type: application/json

{
  "merchant": "VOTRE_CODE",
  "type": "1",
  "phone": "243900XXXXXX",
  "reference": "MM0000201",
  "amount": "100",
  "currency": "CDF",
  "callbackUrl": "https://webhook.site/abc-123-def"
}

# 3. ~3 s plus tard, webhook.site reçoit (URL enregistrée) :
{
  "status": "0",
  "reference": "MM0000201",
  "orderNumber": "abc123..."
}

Format du callback dépôt

Vidipay envoie un POST JSON sur votre callbackUrl après traitement du dépôt. Le contenu dépend de si l'URL est enregistrée dans Callback dépôts.

URL enregistrée (sécurisé)

{
  "status": "0",
  "reference": "MM0000159",
  "orderNumber": "abc123..."
}

URL non enregistrée (complet)

{
  "code": "0",
  "reference": "MM0000159",
  "provider_reference": "TEST-A1B2C3",
  "orderNumber": "abc123..."
}

Champs — URL enregistrée

Champ	Description
`status`	`0` = réussi, `1` = échec
`reference`	Votre référence marchand
`orderNumber`	ID Vidipay (utilisable avec `GET check`)

status : 0 = réussi, 1 = échoué. orderNumber permet d'appeler GET check gratuitement. Pas de provider_reference — pour limiter l'exposition de données.

Champs — URL non enregistrée

Si le callbackUrl de la requête n'est pas dans votre espace Callback, le format complet est envoyé (comportement par défaut pour intégrations existantes).

Bonnes pratiques

Enregistrez chaque environnement (test, staging, production) avec son URL dédiée
Utilisez HTTPS en production
Répondez HTTP 200 à la réception du POST (votre serveur)
Traitez les callbacks de façon idempotente — la même reference peut être notifiée une seule fois logiquement
Pour supprimer une URL : page Callback → bouton Supprimer

Format du callback retrait

Même logique que les dépôts : si l'URL est enregistrée dans Callbacks → retraits, payload minimal { status, reference, orderNumber }. Sinon payload complet avec code et provider_reference.

{
  "status": "0",
  "reference": "PO0000042",
  "orderNumber": "abc123..."
}

Format du callback remboursement

Même logique : si l'URL est enregistrée dans Callbacks → remboursements, payload minimal avec depositReference et depositOrderNumber. Sinon payload complet avec code et provider_reference.

{
  "status": "0",
  "reference": "RF0000042",
  "depositReference": "TEST-372AB382",
  "orderNumber": "abc123...",
  "depositOrderNumber": "aSa1eILN98MAjVd31782336431"
}

7. Forfaits & tokens

Quatre forfaits : Free ( tokens à l'inscription), Standard, Pro et Premier. Les tokens n'ont pas de date d'expiration — achetez un pack pour renouveler votre solde. Paiement en CDF ou USD (taux indicatif 1 USD ≈ CDF).

Forfait	Tokens	Accès API
Free	offerts	Dépôt (`paymentService`) + callback dépôt — pas de payout
Standard	250 — 2 700 CDF / 1.00 USD	Dépôt + callbacks dépôt
Pro	250 ou 500 — 5 000 CDF / 1.85 USD	Standard + refund (refundService)
Premier	500 — 11 000 CDF / 4.07 USD	Accès global : dépôt Mobile Money, Visa (type=2), retrait, refund, callbacks

Forfait actuel : — (connectez-vous)

Consommation tokens API

Action	Coût	Forfait min.
`POST paymentService` (accepté)	-1 token	Free (Mobile Money) / Premier (Visa)
`POST payoutService` (accepté)	-1 token	Premier
`GET check/{orderNumber}`	Gratuit	Free
Erreur validation / auth	0 token	—

Votre compte affiche en permanence dans la navbar :

Forfait — —
Total — — tokens
Utilisés — — tokens
Restants — — tokens

Gérez vos achats sur /facturation/ ou achetez directement sur /achat-token/.

8. Modèles de données

MerchantApiKey

Champ	Description
`merchant_code`	Code envoyé dans `merchant`
`api_token`	Token Bearer `vp_live_...`
`test_phone`	Numéro test paiement Mobile Money (`243900XXXXXX`)
`receive_phone`	Numéro compte dépôt / retrait (`243901XXXXXX`)
`refund_phone`	Numéro test remboursement (`243902XXXXXX`) — dépôt puis `refundService`
`test_card`	Carte Visa test unique — `type=2` (Premier)

ApiDeposit

Journal de chaque requête paymentService.

Champ	Description
`requested_at`	Date/heure de réception
`reference`, `phone`, `amount`, `currency`	Données requête
`callback_url`	URL callback marchand
`payment_mode`	`test` ou `live`
`status`	`recu`, `rejete`, `initie`, `test_ok`, `en_attente`, `reussi`, `echoue`
`solde_avant` / `solde_apres`	Solde tokens avant/après
`token_deducted`	Token consommé ou non
`order_number`	ID Vidipay retourné au marchand

DepositCallback

URLs enregistrées manuellement dans Callback dépôts.

Champ	Description
`url`	URL HTTPS de notification
`label`	Libellé optionnel — nom pour distinguer plusieurs URLs (ex. Production, Test) ; affichage uniquement
`is_active`	URL active ou supprimée

PayoutCallback

URLs enregistrées pour les retraits dans Callbacks.

RefundCallback

URLs enregistrées pour les remboursements (refundService) — forfaits Pro et Premier.

Champ	Description
`url`	URL HTTPS de notification remboursement
`label`	Libellé optionnel (Production, Test, …)
`is_active`	URL active ou supprimée

ApiPayout

Journal de chaque requête payoutService.

Champ	Description
`phone`	Numéro bénéficiaire du transfert
`solde_fonds_avant` / `solde_fonds_apres`	Solde dépôts retraitable avant/après
`solde_avant` / `solde_apres`	Solde tokens API avant/après
`order_number`	ID Vidipay du retrait

ApiRefund

Journal de chaque requête refundService. Lié au dépôt d'origine via deposit et deposit_order_number.

Champ	Description
`reference`	Référence du dépôt à rembourser
`refund_reference`	ID unique de l'opération de remboursement
`deposit`	Lien vers l'`ApiDeposit` réussi correspondant
`status`	`recu`, `rejete`, `initie`, `test_ok`, `reussi`, `echoue`
`order_number`	ID Vidipay du remboursement

9. Interface web

URL	Page
`/dashboard/`	Solde, dépôts reçus, montants CDF/USD
`/apropos/`	Vision, architecture et fonctionnement du système
`/api-workspace/`	Token API, code marchand, numéro test, URLs
`/deposits/`	Journal dépôts + filtres + pagination
`/payouts/`	Journal retraits + solde retraitable + filtres
`/refunds/`	Journal remboursements + solde + filtres (Pro / Premier)
`/callbacks/`	URLs callback dépôts et retraits
`/achat-token/`	Achat de packs tokens
`/facturation/`	Forfaits, quota tokens, packs et historique achats
`/documentation/`	Référence technique API

Page Dépôts — filtres

Devise (CDF, USD, …)
Date début / fin
Recherche téléphone (partielle)
5 résultats par page

10. Comment tester

Tester un callback dépôt

Créez une URL sur https://webhook.site
Ajoutez-la dans Callback dépôts
Utilisez exactement la même URL comme callbackUrl dans paymentService
Numéro de test depuis l'Espace API → callback minimal après ~3 s sur webhook.site
Payload attendu : {"status":"0","reference":"...","orderNumber":"..."}

Avec le numéro de test

Copiez le numéro depuis Espace API
POST paymentService avec une reference unique à chaque appel
Callback simulé sur votre callbackUrl après ~3 secondes
Vérifiez dans Dépôts API

Script Python (`test.py` / `test_payout.py` / `test_refund.py`)

# Dépôt
python test.py
python test.py --full

# Retrait (forfait Premier + solde dépôts)
python test_payout.py
python test_payout.py --deposit-first

# Remboursement (forfait Pro/Premier — mêmes champs que le dépôt réussi)
python test_refund.py --deposit-first

Configurez API_TOKEN_VIDIPAY, MERCHANT_CODE, CALLBACK_URL et PAYOUT_PHONE=243901000003 dans .env.

Postman

POST https://vidipay.tech/api/rest/v1/paymentService
Authorization: Bearer vp_live_...

11. Codes d'erreur API

En cas d'échec, la réponse contient code: "1" et errorCode (ex. VAL_002, AUTH_005). Le détail de chaque code est ci-dessous — ne pas s'appuyer sur un champ message ou cause dans les réponses d'erreur.

Authentification

Code	Libellé	Description	HTTP
`AUTH_001`	Header Authorization manquant	Ajoutez le header : Authorization: Bearer vp_live_... (Espace API).	401
`AUTH_002`	Format Bearer requis	Utilisez Authorization: Bearer VOTRE_TOKEN (pas Basic, pas le token seul).	401
`AUTH_003`	Token API vide	Le header contient « Bearer » mais aucun token après.	401
`AUTH_004`	Format de token incorrect	Le token doit commencer par vp_live_.	401
`AUTH_005`	Token invalide ou révoqué	Régénérez votre token dans Vidipay → Espace API.	401

Requête

Code	Libellé	Description	HTTP
`REQ_001`	JSON invalide	Le corps de la requête n'est pas du JSON valide. Vérifiez Content-Type: application/json.	400
`REQ_002`	Corps de requête invalide	Envoyez un objet JSON {}, pas un tableau [] ni une chaîne brute.	400
`REQ_003`	orderNumber vide	Indiquez l'orderNumber dans l'URL : GET /api/rest/v1/check/{orderNumber}.	400

Validation

Code	Libellé	Description	HTTP
`VAL_001`	Champs obligatoires manquants	Renseignez : merchant, type, reference, phone, amount, currency, callbackUrl.	400
`VAL_002`	Code marchand incorrect	Le champ merchant doit correspondre exactement à votre code Espace API.	400
`VAL_003`	Type de paiement invalide	type doit être 1 (Mobile Money) ou 2 (carte bancaire).	400
`VAL_004`	Référence trop longue	reference : maximum 64 caractères.	400
`VAL_005`	Format téléphone invalide	phone : format 243XXXXXXXXX (12 chiffres, 9 après 243).	400
`VAL_006`	Numéro de test incorrect	Ce numéro 243900… n'est pas votre numéro de test. Utilisez celui de l'Espace API ou un Mobile Money réel.	400
`VAL_007`	Téléphone manquant	Le champ phone est obligatoire.	400
`VAL_008`	Montant invalide	amount doit être un nombre.	400
`VAL_009`	Montant non positif	amount doit être strictement supérieur à 0.	400
`VAL_010`	Montant manquant	Le champ amount est obligatoire.	400
`VAL_011`	Devise invalide	currency : CDF ou USD uniquement.	400
`VAL_012`	callbackUrl invalide	callbackUrl doit être une URL http:// ou https:// complète.	400
`VAL_013`	callbackUrl manquant	Le champ callbackUrl est obligatoire.	400
`VAL_014`	Champs payout obligatoires manquants	Renseignez : merchant, reference, phone (bénéficiaire), amount, currency, callbackUrl.	400
`VAL_015`	Champs refund obligatoires manquants	Renseignez : merchant, reference (dépôt d'origine), phone ou card, amount, currency, callbackUrl.	400
`VAL_016`	Numéro de carte invalide	Carte Visa attendue : 16 chiffres, commence par 4, valide Luhn.	400
`VAL_017`	Carte réelle interdite dans l'API	En production carte, redirigez le client vers paymentUrl (portail Vidipay). N'envoyez pas la vraie carte dans paymentService.	400
`VAL_018`	Carte test requise	Pour type=2 en mode test, envoyez le champ card avec votre carte Visa test (Espace API).	400
`VAL_019`	Payeur requis	Indiquez phone (Mobile Money) ou card (Visa) selon le dépôt d'origine.	400

Métier

Code	Libellé	Description	HTTP
`BIZ_001`	Référence déjà utilisée	Chaque paiement doit avoir une reference unique pour votre compte.	400
`BIZ_002`	Solde tokens insuffisant	Chaque POST paymentService accepté coûte 1 token. Achetez des tokens sur /achat-token/.	400
`BIZ_003`	Déduction token impossible	Erreur temporaire lors du débit du token. Réessayez.	400
`BIZ_004`	Solde dépôts insuffisant	Le montant du retrait dépasse le solde disponible dans la devise demandée (CDF ou USD). La réponse inclut balances, availableBalance et currency.	400
`BIZ_005`	Forfait insuffisant	Cette fonctionnalité nécessite un forfait supérieur (Premier pour payoutService et Visa, Pro pour refund mobile).	403
`BIZ_006`	Dépôt introuvable pour remboursement	Aucun dépôt réussi ne correspond à merchant, reference, phone, amount et currency fournis.	404
`BIZ_007`	Dépôt déjà remboursé	Un remboursement a déjà été initié ou effectué pour ce dépôt.	400

Paiement

Code	Libellé	Description	HTTP
`PAY_001`	Échec initiation paiement	Le paiement Mobile Money n'a pas pu être initié après déduction du token.	400

Retrait

Code	Libellé	Description	HTTP
`PAY_002`	Échec initiation retrait	Le transfert vers le numéro bénéficiaire n'a pas pu être initié après déduction du token.	400

Remboursement

Code	Libellé	Description	HTTP
`PAY_003`	Échec initiation remboursement	Le remboursement n'a pas pu être initié après déduction du token.	400

Vérification

Code	Libellé	Description	HTTP
`CHK_001`	Transaction introuvable	Aucune transaction pour cet orderNumber sur votre compte, ou traitement encore en cours.	404

12. Dépannage rapide

Code	Action
`AUTH_004` / `AUTH_005`	Régénérer le token dans Espace API
`BIZ_002`	/achat-token/
`VAL_002`	Code marchand exact depuis Espace API
`BIZ_001`	Nouvelle `reference` à chaque paiement
`BIZ_006`	Vérifier que le dépôt existe avec les mêmes `reference`, `phone`, `amount`, `currency` et statut réussi
`BIZ_007`	Ce dépôt a déjà un remboursement en cours ou réussi
`CHK_001`	Vérifier `orderNumber` ou attendre fin du traitement
Callback complet au lieu du minimal	`callbackUrl` = URL enregistrée dans Callback dépôts
Pas de callback reçu	URL HTTPS accessible ; webhook.site en test
Montant USD = 0 sur dashboard	Dépôts en CDF — normal

13. Acheter des tokens

Les tokens Vidipay alimentent vos appels API. Chaque pack active ou renforce un forfait (voir § Forfaits & tokens). Achetez sur /achat-token/ ou depuis /facturation/.

Pack	Tokens	Forfait	Prix (CDF / USD)
250 tokens — Standard	250	Standard	2 700 CDF / 1.00 USD
250 tokens — Pro	250	Pro	5 000 CDF / 1.85 USD
500 tokens — Pro	500	Pro	5 000 CDF / 1.85 USD
500 tokens — Premier	500	Premier	11 000 CDF / 4.07 USD

Méthodes acceptées : Mobile Money. Devises : CDF et USD. Taux : 1 USD = CDF (admin : PricingConfig + TokenPackPrice).

Documentation API — paiement Mobile Money & Visa

1. Parcours marchand

2. Identifiants & URLs

3. API paymentService

Endpoint

Corps de la requête

Exemple

Réponse succès (HTTP 200)

Réponse erreur (HTTP 400 / 401 / 404)

Règles importantes

3b. Paiement Visa — paymentService (type=2)

Deux modes

Champs requête (type=2)

Portail payeur (production)

Exemples de requête — multi-langages

Réponses

Erreurs spécifiques carte

4. API payoutService

Endpoint

Corps de la requête

Exemple

Exemple de requête — multi-langages

Réponse succès (HTTP 200)

Erreurs spécifiques retrait

Règles

4b. API refundService

Endpoint

Corps de la requête

Exemple

Exemple de requête — multi-langages

Réponse succès (HTTP 200)

Erreurs spécifiques

Callback remboursement

4c. API balance — soldes retraitables

Endpoint

Réponse succès (HTTP 200)

Exemple de requête — multi-langages

5. API check transaction

Endpoint

Réponse succès

Réponse erreur (HTTP 404)

6. Callbacks marchand

Callback autonome — phase 1 (sans opérateur Mobile Money réel)

Comment configurer un callback dépôt

Libellé optionnel — à quoi ça sert ?

Exemple complet (test avec webhook.site)

Format du callback dépôt

URL enregistrée (sécurisé)

URL non enregistrée (complet)

Champs — URL enregistrée

Champs — URL non enregistrée

Bonnes pratiques

Format du callback retrait

Format du callback remboursement

7. Forfaits & tokens

Consommation tokens API

8. Modèles de données

MerchantApiKey

ApiDeposit

DepositCallback

PayoutCallback

RefundCallback

ApiPayout

ApiRefund

9. Interface web

Page Dépôts — filtres

10. Comment tester

Tester un callback dépôt

Avec le numéro de test

Script Python (test.py / test_payout.py / test_refund.py)

Postman

11. Codes d'erreur API

Authentification

Requête

Validation

Métier

Paiement

Retrait

Remboursement

Vérification

3b. Paiement Visa — paymentService (`type=2`)

Script Python (`test.py` / `test_payout.py` / `test_refund.py`)