Aller au contenu

Paiement mobile avec Djomy : fiche pour l'équipe Flutter

Cette fiche décrit le nouveau paiement de l'API mobile BCard (abonnement Pro et cartes physiques). Elle remplace entièrement le paiement Stripe.


1. Ce qui change

  • Il n'y a plus de SDK Stripe : le paquet flutter_stripe doit être retiré de l'application. Plus de client_secret, plus de PaymentIntent, plus de feuille de paiement native.
  • L'API renvoie désormais une redirect_url : l'application l'ouvre dans un navigateur (page de paiement hébergée par Djomy). L'utilisateur y choisit son moyen de paiement (Orange Money, MTN MoMo, Soutra Money, PayCard, Kulu, carte) et paie.
  • Djomy ne renvoie pas l'utilisateur vers l'application. Quand le navigateur est refermé, c'est l'application qui interroge le statut du paiement.
  • La confirmation réelle est faite côté serveur (notification Djomy ou relecture du statut chez Djomy). L'application ne confirme plus rien elle-même : seul le statut COMPLETED renvoyé par l'API fait foi.
  • Tous les montants sont en GNF (entiers). La devise n'est plus envoyée par l'application.

2. Déroulé pas à pas

Application Flutter                 API BCard                       Djomy
        |                               |                             |
        | 1. POST /api/subscription/    |                             |
        |    upgrade-to-pro  (ou        |                             |
        |    POST /api/physical-cards/  |                             |
        |    {id}/pay)                  |                             |
        |------------------------------>| 2. crée le paiement PENDING |
        |                               |    et la transaction ------>|
        |                               |<----------- redirect_url ---|
        | 3. 201 {payment_id,           |                             |
        |         redirect_url, ...}    |                             |
        |<------------------------------|                             |
        |                               |                             |
        | 4. ouvre redirect_url dans un navigateur ------------------>|
        |                               |        5. l'utilisateur paie|
        | 6. l'utilisateur ferme le navigateur                        |
        |                               |<--- webhook (asynchrone) ---|
        | 7. GET /api/payments/{id}/status  (toutes les 3 s, ~60 s)   |
        |------------------------------>| relit le statut chez Djomy  |
        |                               | et valide si SUCCESS ------>|
        | 8. {status: COMPLETED|PENDING|FAILED}                       |
        |<------------------------------|                             |

Résumé côté application :

  1. Appeler l'endpoint de démarrage (abonnement ou carte) avec le téléphone du payeur.
  2. Ouvrir data.redirect_url dans un navigateur intégré.
  3. À la fermeture du navigateur, interroger GET /api/payments/{payment_id}/status.
  4. Selon data.status : COMPLETED (succès), FAILED (proposer de réessayer), PENDING (continuer à interroger, puis afficher « paiement en cours de vérification »).

3. Authentification

Tous les endpoints ci-dessous exigent un JWT. Le jeton s'obtient par POST /api/auth/login (Content-Type: application/json) :

{"email": "utilisateur@example.com", "password": "mot-de-passe"}

200 OK :

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "…",
  "user": {"id": 5, "email": "utilisateur@example.com", "name": "Prénom Nom", "roles": ["ROLE_USER"]}
}

token est à envoyer dans Authorization: Bearer <token>. Erreurs de connexion : 400 ({"error": "Email et mot de passe requis"}), 401 ({"error": "Identifiants invalides"}), 403 si l'e-mail n'est pas vérifié ou le compte pas activé ({"error": "...", "requires_verification": true}). Attention : cet endpoint de connexion utilise l'enveloppe {"error": ...}, différente de celle des endpoints de paiement.


3 bis. Conventions communes

  • En-têtes : Authorization: Bearer <JWT> et, pour les requêtes avec corps, Content-Type: application/json.
  • Enveloppe : toutes les réponses de ces endpoints ont la forme {"success": true, "data": {...}} ou {"success": false, "message": "...", "error_code": "..."}. message est un texte en français affichable à l'utilisateur ; error_code sert à la logique de l'application.
  • 401 (jeton absent, invalide ou expiré), identique pour tous les endpoints :
{"code": 401, "message": "JWT Token not found"}

(ou "Expired JWT Token" / "Invalid JWT Token"). Rafraîchir le jeton ou reconnecter l'utilisateur.

Téléphone du payeur (payer_phone)

  • Format conseillé : +224 6XX XX XX XX. Sont aussi acceptés : +224622000000, 224622000000, 622000000 (numéro local à 9 chiffres commençant par 6). Les espaces sont ignorés.
  • Le serveur normalise le numéro (00224622000000) : l'application n'a pas à le faire.
  • Numéro invalide : réponse 400 avec error_code: "invalid_phone", rien n'est créé.

4. Endpoints

4.1 Démarrer le paiement de l'abonnement Pro

POST /api/subscription/upgrade-to-pro

Corps :

Champ Type Obligatoire Description
payment_method string oui Seule valeur acceptée : "djomy"
billing_cycle string non "monthly" (défaut) ou "yearly"
payer_phone string oui Téléphone du payeur (voir ci-dessus)
{
  "payment_method": "djomy",
  "billing_cycle": "monthly",
  "payer_phone": "+224 622 00 00 00"
}

201 Created (paiement démarré) :

{
  "success": true,
  "data": {
    "payment_id": 12,
    "subscription_id": 18,
    "redirect_url": "https://sandbox.djomy.africa/c/30525X713",
    "status": "PENDING",
    "amount": 50000,
    "currency": "GNF"
  }
}

À retenir :

  • Garder payment_id : c'est l'identifiant à utiliser pour interroger le statut.
  • Si l'utilisateur relance le paiement (même plan, même cycle) alors qu'un abonnement PENDING existe, le même payment_id est repris et une nouvelle redirect_url est fournie.
  • L'abonnement n'est pas activé à ce stade : il l'est seulement quand le statut devient COMPLETED.

400 Bad Request (moyen de paiement non supporté) :

{
  "success": false,
  "message": "Méthode de paiement non supportée : seule la valeur « djomy » est acceptée.",
  "error_code": "invalid_payment_method"
}

400 Bad Request (téléphone invalide) :

{
  "success": false,
  "message": "Numéro de téléphone invalide. Format attendu : +224 6XX XX XX XX",
  "error_code": "invalid_phone"
}

Autres 400 : invalid_billing_cycle (« Cycle de facturation invalide ») et already_subscribed (« Vous avez déjà un abonnement actif »).

404 Not Found (plan Pro indisponible) :

{
  "success": false,
  "message": "Le plan Pro n'est pas disponible",
  "error_code": "plan_unavailable"
}

409 Conflict (un paiement est déjà en cours, ou il est déjà confirmé) :

{
  "success": false,
  "message": "Un paiement est déjà en cours. Réessayez dans 8 minute(s).",
  "error_code": "in_progress",
  "data": {"payment_id": 12, "subscription_id": 18}
}

Ou, si Djomy indique que le paiement précédent est en réalité réussi (le serveur le valide au passage) :

{
  "success": false,
  "message": "Ce paiement a déjà été confirmé.",
  "error_code": "already_paid",
  "data": {"payment_id": 12, "subscription_id": 18}
}

Dans les deux cas 409, ne pas rouvrir de navigateur : utiliser data.payment_id pour interroger le statut du paiement (§4.3). Même si l'application n'a pas mémorisé l'identifiant, il est donc toujours récupérable.

400 Bad Request not_payable (le paiement existant ne peut plus être payé : il n'est ni en attente ni réussi) :

{
  "success": false,
  "message": "Ce paiement ne peut plus être effectué.",
  "error_code": "not_payable",
  "data": {"payment_id": 12, "subscription_id": 18}
}

503 Service Unavailable (Djomy non configuré ou injoignable) :

{
  "success": false,
  "message": "Le paiement en ligne est momentanément indisponible. Veuillez réessayer plus tard.",
  "error_code": "not_configured"
}

Autres error_code en 503 : gateway_unavailable (Djomy a refusé ou n'a pas répondu) et check_failed (la transaction précédente n'a pas pu être relue : réessayer dans un instant). Une erreur inattendue renvoie 500 avec error_code: "internal_error".

4.2 Démarrer le paiement d'une carte physique

POST /api/physical-cards/{id}/pay

{id} est l'identifiant de la carte physique, obtenu à la création de la commande (POST /api/physical-cards/create-order). La carte doit appartenir à l'utilisateur et avoir un prix strictement positif. Le corps ne contient plus de devise : le serveur utilise toujours le GNF.

Corps :

{"payer_phone": "+224 622 00 00 00"}

201 Created :

{
  "success": true,
  "data": {
    "payment_id": 13,
    "physical_card_id": 7,
    "order_id": 15,
    "redirect_url": "https://sandbox.djomy.africa/c/7DA21B904",
    "status": "PENDING",
    "amount": 150000,
    "currency": "GNF"
  }
}

Erreurs (même enveloppe que ci-dessus) :

HTTP error_code Cas
400 invalid_phone Téléphone invalide
400 not_payable Le paiement existant ne peut plus être payé (réponse avec data.payment_id, data.physical_card_id, data.order_id)
400 free_card Prix nul : la carte est offerte, aucun paiement requis (réponse avec is_free: true)
401 Jeton absent ou expiré
403 already_paid Carte déjà payée ou en traitement
404 Carte introuvable ou appartenant à un autre utilisateur (message: « Carte physique non trouvée »)
409 in_progress, already_paid Paiement déjà en cours ou déjà confirmé (réponse avec data.payment_id, data.physical_card_id, data.order_id)
409 not_payable La commande de la carte ne peut plus être payée en ligne (même forme de data)
503 not_configured, gateway_unavailable, check_failed Djomy indisponible

Exemple de 409 :

{
  "success": false,
  "message": "Un paiement est déjà en cours. Réessayez dans 8 minute(s).",
  "error_code": "in_progress",
  "data": {"payment_id": 13, "physical_card_id": 7, "order_id": 15}
}

Exemple de 404 :

{"success": false, "message": "Carte physique non trouvée"}

4.3 Interroger le statut d'un paiement (endpoint à utiliser pour tout)

GET /api/payments/{id}/status, où {id} est le payment_id reçu au démarrage.

Aucun corps. Le serveur relit le statut chez Djomy et valide le paiement (activation de l'abonnement, confirmation de la commande ou de la carte) si Djomy confirme le succès.

Pour ménager Djomy, un statut non réussi est mis en cache 6 secondes côté serveur : interroger toutes les 3 secondes reste correct (une réponse sur deux vient du cache), mais inutile de le faire plus vite. Un succès n'est jamais mis en cache. Un paiement démarré depuis plus d'une heure n'est plus relu chez Djomy par cet endpoint : il reste PENDING et la réconciliation du serveur prend le relais (voir FAQ).

200 OK, paiement en cours (ou pas encore confirmé) :

{
  "success": true,
  "data": {
    "payment_id": 12,
    "status": "PENDING",
    "subscription_status": "PENDING",
    "order_status": null
  }
}

200 OK, paiement réussi (abonnement activé) :

{
  "success": true,
  "data": {
    "payment_id": 12,
    "status": "COMPLETED",
    "subscription_status": "ACTIVE",
    "order_status": null
  }
}

200 OK, paiement échoué ou annulé chez Djomy (rien n'est modifié côté BCard, on peut réessayer) :

{
  "success": true,
  "data": {
    "payment_id": 12,
    "status": "FAILED",
    "subscription_status": "PENDING",
    "order_status": null
  }
}

200 OK, Djomy n'a pas pu être interrogé (erreur temporaire) : le statut reste PENDING et un indicateur est ajouté. Ce n'est pas une erreur : continuer à interroger.

{
  "success": true,
  "data": {
    "payment_id": 12,
    "status": "PENDING",
    "subscription_status": "PENDING",
    "order_status": null,
    "check_error": true
  }
}

404 Not Found (paiement inexistant ou appartenant à un autre utilisateur) :

{"success": false, "message": "Paiement introuvable"}

401 : voir §3.

Champs : status vaut COMPLETED, PENDING ou FAILED. subscription_status (PENDING, ACTIVE…) est renseigné pour un paiement d'abonnement, order_status (par exemple En traitement) pour un paiement de carte physique ; l'autre vaut null. Pour un paiement de carte, la réponse de POST /api/physical-cards/{id}/confirm-payment ajoute physical_card_id et card_status.

4.4 Routes conservées pour compatibilité

Ces deux routes existent toujours mais ne confirment plus rien à partir d'un identifiant Stripe : elles font la même vérification que le §4.3 et renvoient la même réponse. Pour tout nouveau code, utiliser GET /api/payments/{id}/status.

  • POST /api/subscription/confirm-payment avec le corps {"payment_id": 12}. 400 si payment_id manque ({"success": false, "message": "payment_id requis"}), 404 si le paiement n'est pas celui de l'utilisateur.
  • POST /api/physical-cards/{id}/confirm-payment (corps ignoré). 404 si la carte ou son paiement est introuvable.

4.5 Historique des paiements (rappel)

GET /api/payments, GET /api/payments/{id} et GET /api/payments/stats fonctionnent. Les objets paiement exposent maintenant currency (toujours "GNF"), provider ("djomy") et provider_reference, et n'ont plus stripe_payment_intent_id.


5. Recommandations côté application

  1. Ouvrir redirect_url dans un navigateur intégré (url_launcher en mode LaunchMode.inAppBrowserView, ou un paquet d'in-app browser). Ne pas utiliser de WebView sans barre de navigation : la page Djomy peut ouvrir des étapes de confirmation (OTP, 3DS).
  2. À la fermeture du navigateur, interroger GET /api/payments/{id}/status toutes les 3 secondes, pendant 60 secondes au maximum.
  3. COMPLETED : arrêter, afficher le succès, recharger l'abonnement (GET /api/subscription/current) ou la commande.
  4. FAILED : arrêter, afficher « le paiement n'a pas abouti » et proposer de réessayer (nouvel appel de démarrage).
  5. PENDING : continuer. Passé 60 secondes, arrêter et afficher « Paiement en cours de vérification » avec un bouton « Vérifier à nouveau » (qui relance une interrogation du statut).
  6. Gérer les trois statuts COMPLETED, PENDING et FAILED, ainsi que check_error: true (traité comme PENDING).
  7. Mémoriser le payment_id (stockage local) tant que le paiement n'est pas COMPLETED ou FAILED, pour pouvoir reprendre la vérification si l'application est tuée (voir FAQ).
  8. Téléphone : prérenseigner le champ avec +224 6XX XX XX XX, valider côté application que le numéro a 9 chiffres commençant par 6, mais laisser le serveur faire foi (il normalise et peut répondre 400).
  9. Ignorer la page web BCard qui peut s'afficher après le paiement. Après le paiement, Djomy peut renvoyer le navigateur intégré vers une page web de BCard (/payment/djomy/return/...). Cette page valide le paiement côté serveur puis redirige vers une page web qui exige une connexion web : l'utilisateur mobile peut donc voir la page de connexion web de BCard. C'est normal et sans conséquence : il faut l'ignorer et fermer le navigateur, puis interroger l'API. Seul le statut renvoyé par l'API fait foi. Recommandation : détecter dans le navigateur intégré une URL contenant /payment/djomy/return/ pour le fermer automatiquement, par exemple avec flutter_inappwebview (shouldOverrideUrlLoading ou onLoadStart dans InAppWebView, ou le callback équivalent de ChromeSafariBrowser / InAppBrowser), puis lancer l'interrogation du statut. Avec url_launcher seul, cette détection n'est pas possible : l'utilisateur ferme alors le navigateur lui-même.
  10. Ne pas considérer le paiement comme réussi parce que le navigateur est fermé ou que l'utilisateur a vu « Paiement effectué avec succès » sur la page Djomy : seul status: "COMPLETED" compte.
  11. 409 : ne pas rouvrir de navigateur ; afficher message et interroger le statut de data.payment_id.
  12. 503 : afficher message et proposer de réessayer plus tard.
  13. Éviter le double appui : désactiver le bouton « Payer » pendant l'appel de démarrage.

6. Données de test (sandbox)

Utiliser des montants ≤ 10 000 GNF pour Soutra Money (limite annoncée par Djomy, non vérifiée). PayCard n'a pas cette limite : paiement de 475 000 GNF validé en DEV le 20/10/2026. Pour les cartes : date d'expiration future, CVV sur 3 chiffres au choix.

Cartes bancaires

Numéro de carte Mode 3DS Résultat attendu
2303779999000275 Frictionless Succès
2303779999000408 Challenge Succès
2303779999000291 Frictionless Échec (non authentifié)
2303779999000317 Frictionless Échec (indisponible)
2303779999000424 Challenge Échec (non authentifié)
2303779999000432 Challenge Échec (indisponible)

PayCard

  • Numéro de compte : 537417414
  • Code OTP sur la page de confirmation : 0000

Soutra Money

  • Numéro de compte : 622356781
  • PIN : 1111

Orange Money

  • Tous les paiements Orange Money échouent en sandbox. C'est le comportement normal, annoncé par Djomy.

MTN MoMo, Kulu

  • Pas de données de test fournies : à ne pas tester pour l'instant.

Constats des premiers essais côté web (voir paiement-djomy-tests.md) : PayCard fonctionne de bout en bout ; la carte bancaire et le PIN de transaction Soutra Money posent encore problème chez Djomy. Privilégier PayCard pour valider le parcours.


7. Endpoints supprimés ou renommés

Avant Après
POST /api/subscription/upgrade-to-pro avec payment_method: "credit_card" renvoyant client_secret et payment_intent_id Même route, mais payment_method: "djomy" + payer_phone, réponse redirect_url + payment_id (201)
payment_method: "orange_money" sur upgrade-to-pro (renvoyait 503) Supprimé : seule la valeur djomy est acceptée (400 sinon)
POST /api/physical-cards/{id}/create-payment-intent Supprimée, remplacée par POST /api/physical-cards/{id}/pay
POST /api/subscription/confirm-payment avec payment_intent_id Route conservée, corps {"payment_id": ...}, vérifie le statut
POST /api/physical-cards/{id}/confirm-payment avec payment_intent_id Route conservée, corps ignoré, vérifie le statut
(nouveau) GET /api/payments/{id}/status
stripe_payment_intent_id dans GET /api/payments et GET /api/payments/{id} Retiré ; ajout de provider et provider_reference

À retirer de l'application

  • Le paquet flutter_stripe (pubspec.yaml), son initialisation (Stripe.publishableKey, etc.) et les appels Stripe.instance.initPaymentSheet / presentPaymentSheet / confirmPayment.
  • La configuration native liée à Stripe (Android : thème Theme.MaterialComponents imposé par le SDK, MainActivity en FlutterFragmentActivity, règles ProGuard Stripe ; iOS : clés spécifiques au SDK) si elle n'a plus d'autre usage.
  • La clé publique Stripe embarquée dans l'application.
  • Toute lecture des champs client_secret, payment_intent_id et stripe_payment_intent_id.
  • Le champ currency dans les requêtes de paiement.

8. FAQ

L'utilisateur ferme l'application pendant le paiement. Le paiement continue chez Djomy et le serveur est prévenu par notification : l'abonnement ou la carte sera confirmé même si l'application est fermée. À la réouverture, interroger le statut du payment_id mémorisé (ou recharger GET /api/subscription/current / la commande). Si le payment_id est perdu, GET /api/payments liste les paiements récents avec leur statut.

L'utilisateur a payé mais le statut reste PENDING. Cela peut durer quelques secondes à quelques minutes (délai de la notification Djomy). Continuer à interroger puis afficher « Paiement en cours de vérification » avec un bouton « Vérifier à nouveau ». Le serveur dispose en plus d'une tâche de réconciliation qui valide les paiements restés en attente. Si le statut reste PENDING plus de quelques minutes après un paiement réussi, relever l'heure, l'e-mail du compte, le payment_id et la référence affichée sur la page Djomy, et les transmettre à l'équipe backend.

Le paiement a démarré il y a plus d'une heure et reste PENDING. Passé 60 minutes, GET /api/payments/{id}/status ne relit plus Djomy et répond PENDING sans interroger la passerelle. La réconciliation du serveur (tâche planifiée qui relit les paiements en attente chez Djomy) prend le relais : si l'utilisateur a bien payé, le paiement passera COMPLETED tout seul. Ne pas boucler sur l'endpoint ; afficher « Paiement en cours de vérification » et inviter à réessayer plus tard. Si le paiement n'a pas abouti, l'utilisateur peut relancer un paiement (nouvel appel de démarrage).

Le statut est FAILED mais l'utilisateur dit avoir payé. FAILED signifie que Djomy a répondu « échec » ou « annulé » pour cette transaction. Proposer de réessayer. Si l'utilisateur a bien été débité, transmettre le payment_id et la référence Djomy à l'équipe backend.

L'utilisateur clique deux fois sur « Payer ». Le serveur réutilise le même paiement. Si une transaction est encore en cours depuis moins de 10 minutes, l'API répond 409 (in_progress) : afficher le message et interroger le statut.

check_error: true dans la réponse de statut. Djomy n'a pas pu être interrogé à cet instant. Le statut est PENDING : réessayer à l'intervalle normal.

Puis-je encore payer en carte bancaire via l'application ? Oui, mais sur la page Djomy (si la carte est activée sur le compte marchand). Il n'y a plus de saisie de carte dans l'application.

Quel payment_method voit-on dans l'historique ? DJOMY pour les nouveaux paiements. Les anciens paiements Stripe gardent CREDIT_CARD.