Brief frontend : liens de paiement et portefeuille du technicien (Expert Hub)

Date : 2026-10-10 · Destinataire : dev frontend apps/expert-hub · API : https://live.jmoai.net Statut backend : lot 1 en production depuis le 2026-10-10. Les routes ci-dessous sont actives. Le lot 2 (retrait, achat de licence avec le solde) suit.

Ce brief remplace la « Note de cadrage : système de génération de liens de paiement & portefeuilles techniciens ».

1. Le modèle (décision du propriétaire)

J+SERVICES vend, le technicien réalise.

Le client du technicien paie J+SERVICES, sur notre compte de paiement.
Nous créditons ensuite le compte du technicien.
Avec ce solde, le technicien génère des licences pour ses clients. Au lot 2, il pourra aussi en demander le retrait.

Deux types de lien :

`link_type`	Usage	Ce qui est crédité au technicien
`INVOICE`	facture d’un service : intervention, installation, maintenance, matériel…	montant moins la commission de la catégorie (`fee_pct`)
`LICENSE_SALE`	encaisser le prix d’une licence que le technicien livrera lui-même	100 % du montant

La commission dépend de la catégorie, et elle est figée au moment de la création du lien.

2. Corrections par rapport à votre note

Votre note	Réalité
devise `XAF`	`XOF` (F CFA BCEAO)
`expert_id` dans le corps	interdit : l’identité vient du jeton. Un technicien ne crée des liens que pour lui-même
Campay, ou un agrégateur choisi par le front	c’est le backend qui choisit : compte J+SERVICES (FedaPay aujourd’hui, FeexPay ensuite). Le front n’appelle jamais un agrégateur
`POST /api/v1/webhooks/payments`	pas de route webhook à appeler ni à connaître côté front
« vérifier la signature du webhook »	c’est l’affaire du backend : il relit le statut chez l’agrégateur, montant compris
tables `expert_wallets` / `wallet_transactions`	registre comptable existant, en partie double. Le front lit seulement `GET /api/v1/expert/wallet`
Socket.io	pas de temps réel au lot 1 : un e-mail et une notification push. Actualisez le solde à l’ouverture de l’écran

3. Authentification

Mêmes règles que les autres routes de l’espace technicien :

Authorization: Bearer <jeton de session Supabase> d’un compte technicien approuvé, avec un e-mail confirmé ;
ou le jeton revendeur (partner_token).

Sans identité valide, la réponse est 401.

4. Routes

Catégories de service

GET /api/v1/expert/billing/categories

{
  "success": true,
  "data": [{ "code": "INSTALLATION", "label": "Installation", "platform_fee_pct": 15 }]
}

Affichez le taux à côté de chaque catégorie, avec le net calculé en direct : « Vous recevrez 8 500 F sur 10 000 F ».

Créer un lien

POST /api/v1/expert/billing/payment-links

{
  "link_type": "INVOICE",
  "category_code": "INSTALLATION",
  "amount": 15000,
  "description": "Installation routeur MikroTik hEX lite",
  "customer_email": "client@example.com",
  "customer_phone": "22997000000",
  "expires_in_hours": 72
}

category_code : obligatoire pour INVOICE, absent pour LICENSE_SALE.
amount : nombre entier en XOF, de 100 à 2 000 000.
description : 120 caractères au maximum, texte simple.
customer_email / customer_phone : facultatifs, servent seulement au suivi.

Réponse 201 :

{
  "success": true,
  "data": {
    "id": "…",
    "url": "https://live.jmoai.net/api/v1/pay/expert/…",
    "link_type": "INVOICE",
    "amount": 15000,
    "fee_pct": 15,
    "net_for_expert": 12750
  }
}

Proposez Copier, WhatsApp et QR code sur url. Ne construisez jamais l’URL vous-même.

Mes liens

GET /api/v1/expert/billing/payment-links?page=1&limit=50 Statuts possibles : OPEN, PAID, EXPIRED, CANCELED.

Statut	Libellé conseillé
`OPEN`	En attente de paiement
`PAID`	Payé (avec la date)
`EXPIRED`	Expiré
`CANCELED`	Annulé

Mon portefeuille

GET /api/v1/expert/wallet → solde disponible en XOF, puis l’historique des mouvements : crédits par lien payé et, plus tard, les débits.

Affichez « Solde disponible ».
Pour chaque mouvement : la date, le libellé, le montant, la référence du lien.

5. Ce que voit le client du technicien

Le lien ouvre une page de paiement « Encaissé par J+SERVICES », avec la description et le montant. Les coordonnées du technicien n’y apparaissent jamais. Après le paiement, le technicien reçoit :

un e-mail « 💰 Paiement reçu : <montant> F CFA — <description> », avec le brut, la commission, le net et le nouveau solde ;
une notification push, s’il a l’app.

6. À venir (lot 2), ne pas développer encore

Générer une licence en payant avec le solde.
Demander un retrait du solde vers son mobile money.

Prévoyez simplement deux boutons inactifs, « Générer une licence avec mon solde » et « Retirer », marqués « Bientôt ».

7. Codes d’erreur à gérer

HTTP	Cas	Afficher
400	montant hors bornes, catégorie inconnue ou inactive, description trop longue	le message renvoyé
401	session absente ou expirée	renvoyer vers la connexion
403	compte non technicien	« Candidature en cours »
429	trop de liens créés en peu de temps	« Réessayez dans un instant »

Le contrat détaillé, avec tous les champs, est publié ici : https://doc.jmoai.net/CONTRAT-API-LIENS-TECHNICIEN-PORTEFEUILLE (sur le serveur : ssh root@161.97.64.197 'cat /root/projects/jservices-api/docs/CONTRAT-API-LIENS-TECHNICIEN-PORTEFEUILLE.md'). En cas d’écart avec ce brief, c’est le contrat qui fait foi.