AGRÉGATEUR UniPayWeb · ESPACE MARCHAND

Encaisser, suivre et rapprocher vos règlements depuis un seul environnement sécurisé

UniPayWeb permet de commencer avec un lien QR simple, puis d’automatiser les commandes par API lorsque votre organisation est certifiée. Le marchand conserve son métier et ses factures ; l’Agrégateur orchestre le QR bancaire officiel, le terminal de paiement, les états vérifiables et le retour signé vers le serveur déclaré.

Principe de confianceRéférence unique · statut vérifiable · notification signée · rapprochement par devise

COMPRENDRE LE PORTAIL

Un parcours financier lisible, de la commande au règlement confirmé

Le portail marchand relie votre activité au moteur bancaire UniPayWeb sans vous donner accès aux systèmes internes. Votre serveur décrit une facture ; UniPayWeb crée ou reconnaît le QR officiel, présente le terminal au payeur, contrôle le règlement et restitue un état exploitable par votre site.

01

Une preuve commune

La facture, le QR, le paiement et le retour utilisent une référence traçable. Votre site ne déclare jamais lui-même qu’un paiement a réussi.

02

Deux niveaux d’intégration

Commencez avec un lien QR créé dans BankingServices, puis adoptez l’API lorsque votre serveur et votre organisation sont prêts.

03

Un suivi maîtrisé

La sandbox sépare les essais de la production, journalise les événements et permet de fermer ou révoquer les sessions marchandes.

04

Des canaux maîtrisés

Le marchand pilote ses encaissements depuis un contrat unifié, tandis que chaque canal est activé selon son périmètre d’habilitation.

05

Des erreurs actionnables

Chaque incident de communication fournit un code stable, une explication, une résolution proposée, un indicateur de reprise et une référence de corrélation.

06

Une lecture financière nette

Montant brut, frais bancaires, frais Agrégateur, frais opérateur et net restent distingués par devise pour faciliter contrôle et rapprochement.

  1. QualifierCompte bancaire professionnel ou institutionnel actif, domaine HTTPS et responsable identifié.
  2. ChoisirLien QR pour une intégration légère, ou API pour créer une intention à chaque commande.
  3. TesterIdentifiants sandbox distincts, scénarios contrôlés, journal et états en temps réel.
  4. CertifierRecette technique, contrat, sécurité du webhook et validation de mise en production.
  5. ExploiterSuivre règlements, preuves, notifications et rapprochements selon les capacités habilitées.

Autonomie sans abandon de contrôle : le tableau de bord réunit opérations, journal temps réel, opérateurs habilités, états d’erreur et résolutions proposées. Votre site ne manipule ni mot de passe bancaire, ni clé opérateur, ni écriture comptable ; il conserve sa commande et attend la confirmation signée correspondant exactement à sa référence, son montant et sa devise.

MODE 1

Lien permanent QR dépôt

Accessible avec un compte bancaire

Pour qui ?

Marchands souhaitant intégrer un bouton, un lien ou un QR sans développer une connexion API.

Un lien créé puis réutilisé

Le bénéficiaire crée la proforma dans sa session bancaire, puis génère son lien public. Il contrôle compte, devise, montant, motif, expiration et nombre d’utilisations, et peut saisir l’URL HTTPS de réponse de son site. Le site tiers ne fabrique ni QR ni reçu bancaire.

Parcours du payeur

Le lien ouvre le terminal UniPayWeb avec le bénéficiaire et la référence du QR. Le payeur choisit un règlement interne ou un opérateur externe réellement activé. La page attend la décision serveur et affiche confirmation, attente ou refus ; une simple redirection ne prouve jamais le paiement.

Prérequis du mode QR

  • Compte bancaire UniPayWeb actif du bénéficiaire
  • Proforma/QR officiel non expiré
  • Montant, devise, motif et usages définis dans BankingServices
  • URL HTTPS facultative pour le lien seul, mais obligatoire pour recevoir les callbacks
  • Clé HMAC remise une seule fois si le retour est activé
  • Rapprochement par référence et reçu bancaire confirmé
Créer ou gérer un QR dépôt
MODE 2

Intégration API marchande

Habilitation et certification requises

Identité du marchand

Réception des confirmations

Services marchands

  • Intention idempotente rattachée à une commande
  • Création du QR bancaire officiel avec une utilisation par défaut
  • Présentation du terminal UniPayWeb au payeur
  • Suivi du statut, journal et rapprochement par référence
  • Identifiants et périmètres distincts selon l’environnement

Le contrat remis au marchand précise les services et canaux habilités pour son organisation.

Continuité et reprise

Les callbacks sont signés, horodatés et protégés contre le rejeu. Une livraison impossible est journalisée avec sa cause et sa résolution ; le paiement n’est ni recréé ni débité une seconde fois.

Avantage d’intégration

Une seule logique de commande et de retour réduit les adaptations propres à chaque canal. Les opérateurs ne deviennent utilisables qu’après activation contractuelle et contrôle de leur santé.

Saisissez un domaine et un webhook HTTPS valides pour préparer la demande.
ESPACE SÉCURISÉ

Sandbox marchande en temps réel

Non connecté

Authentification HTTPS

Les identifiants ne sont jamais enregistrés dans le stockage du navigateur.

Obtention de l’accès

Le compte marchand est délivré après vérification du compte bancaire professionnel ou institutionnel, du domaine HTTPS, du webhook et du contrat sandbox.

Commencer depuis le compte bancaire

L’ouverture d’un espace ou d’une session marchande exige un compte bancaire professionnel, société, organisation ou institution officiellement migré et actif. Un compte personnel simple doit terminer sa migration dans BankingServices.

CENTRE D’INTÉGRATION

Documentation sandbox marchande

Contrat HTTPS public

Ce guide permet de préparer et vérifier une intégration sans exposer les systèmes internes. Utilisez exclusivement les identifiants de l’environnement remis à votre organisation. Les secrets restent sur votre serveur et ne doivent jamais être placés dans le navigateur, une URL ou un dépôt de code.

1. Obtenir l’accès

Compte bancaire professionnel ou institutionnel actif, domaine HTTPS et webhook validé, puis émission séparée du client_id et du secret sandbox.

2. Ouvrir une session

Authentifiez-vous en HTTPS. Le portail crée un cookie HttpOnly, Secure et SameSite=Strict ; aucun jeton n’est stocké localement.

3. Créer l’intention

Envoyez une référence, un montant, une devise et une clé d’idempotence stable. Une même commande ne doit produire qu’un seul QR.

4. Tester le terminal

Ouvrez uniquement l’URL retournée. Une ouverture ou une redirection ne prouve jamais le règlement.

5. Suivre l’état

Consultez l’intention, le tableau de bord ou le flux temps réel. Seul un état final confirmé autorise la mise à jour de la facture.

6. Vérifier le callback

Contrôlez le corps brut, la signature HMAC, l’horodatage, l’identifiant d’événement et la correspondance montant, devise et référence.

Endpoints publics du portail marchand
POST /api/merchant/v1/auth/tokenGET /api/merchant/v1/sessionGET /api/merchant/v1/dashboardGET /api/merchant/v1/events?after=0GET /api/merchant/v1/events/streamPOST /api/merchant/v1/payment-intentsGET /api/merchant/v1/payment-intents/{id}POST /api/merchant/v1/auth/logout

Le retrait appartient au périmètre de production certifié et n’est pas un scénario financier sandbox.

Exemple : authentification serveur
POST /api/merchant/v1/auth/token
Content-Type: application/json

{
  "client_id": "sandbox_votre_identifiant",
  "client_secret": "secret_remis_une_seule_fois"
}

Réponse attendue : HTTP 200 et cookie sécurisé. Une erreur contient code, message, resolution, retryable et correlation_id.

Exemple : créer une intention idempotente
POST /api/merchant/v1/payment-intents
Idempotency-Key: CMD-2026-000001-UNIQUE
Content-Type: application/json

{
  "merchant_reference": "CMD-2026-000001",
  "amount": 1,
  "currency": "USD",
  "description": "Commande de recette",
  "usage_policy": "SINGLE",
  "max_uses": 1
}

Une création acceptée retourne l’intention, la référence du QR bancaire officiel, son état et l’URL du terminal. Réutiliser la même clé avec le même contenu renvoie le même résultat ; avec un contenu différent, la requête est refusée.

Structure du callback signé
Headers :
X-UniPay-Feedback-Event
X-UniPay-Feedback-Id
X-UniPay-Feedback-Signature
X-UniPay-Feedback-Signature-Algorithm: HMAC-SHA256
X-UniPay-Feedback-Timestamp

Corps :
{
  "schema": "UNIPAY_DEPOSIT_EXTERNAL_FEEDBACK_V1",
  "event": "PAYMENT_SETTLED",
  "status": "SUCCESS",
  "event_id": "DEP_FEEDBACK_...",
  "proforma_reference": "DEP_...",
  "operation_ref": "...",
  "gross_amount": 1,
  "fee_amount": 0,
  "net_amount": 1,
  "currency": "USD",
  "occurred_at": 1789554294586
}

Calculez HMAC-SHA256 sur les octets exacts du corps reçu, comparez en temps constant, refusez un horodatage ancien et mémorisez event_id. Un événement authentique déjà traité reçoit une réponse 2xx sans second effet.

Scénarios de recette autonomes

S01 Connexion valide : 200 et cookie sécurisé.

S02 Secret incorrect : 401 explicite.

S03 Accès sans session : 401.

S04 Intention valide : QR prêt.

S05 Rejeu identique : même intention, aucun second QR.

S06 Même clé, contenu différent : conflit.

S07 Donnée invalide : 400 avec résolution.

S08 Consultation : état cohérent.

S09 Événements : progression sans doublon.

S10 Callback signé : accepté une fois.

S11 Signature invalide ou ancienne : refus.

S12 Déconnexion : session révoquée.

Statuts, erreurs et reprise

RECEIVED commande reçue, ne pas livrer.

QR_READY terminal disponible, ne pas livrer.

PAID / PAYMENT_SETTLED règlement confirmé.

FAILED opération refusée ou communication épuisée.

Une erreur est rejouable uniquement si retryable=true. Conservez le correlation_id MCOM. Pour HTTP 429, respectez retry_after_seconds. Ne recréez jamais une commande uniquement à cause d’un délai réseau.

Limites et passage en production

Le sandbox marchand valide le contrat UniPayWeb, la création du QR, le terminal, les états, les journaux et les callbacks. Aucun opérateur Mobile Money n’est présenté comme actif tant que son contrat n’est pas installé et certifié. La production exige identité marchande, compte éligible, domaine et webhook HTTPS, recette réussie, rotation des secrets et validation contractuelle.

Vérifier la santé HTTPS
CADRE D’UTILISATION

Contrat API Agrégateur UniPayWeb

Serveur à serveur

Authentification

Les accès sont individuels, limités au marchand et séparés entre sandbox et production. Aucun secret ne doit être placé dans le navigateur.

Intégrité

Chaque requête métier utilise une référence unique. Les notifications sont signées, horodatées et protégées contre le rejeu.

Statut

Seul un statut final vérifié autorise la livraison. Une attente ou un délai réseau ne constitue jamais une preuve d’échec.

Données

Les données sensibles, secrets, mots de passe et documents d’identité sont interdits dans les métadonnées marchandes.

Règlement net

Montant brut − frais interne − frais externe Agrégateur = montant net réglé. Chaque composante possède sa propre écriture, sa devise et sa preuve; elles ne sont jamais fusionnées.

Responsabilités

Le marchand protège son serveur et traite sa facture. UniPayWeb assure l’orchestration, la preuve technique et la notification du règlement.

Cadre de responsabilité et mentions

L’Agrégateur UniPayWeb est un portail du Méta-Écosystème fintech UniPayWeb SARL. L’accès à la production dépend de l’identification du marchand, du contrat applicable, de la juridiction concernée et d’une recette technique validée. Cette page ne délivre aucune autorisation réglementaire et n’expose aucune route interne Banque–Agrégateur.

Guide marchand

PRODUCTION CONTRÔLÉE

Tester un dépôt ou un retrait réel

Attention : cette fenêtre agit sur les soldes réels. Chaque ordre possède une clé d’idempotence et reste journalisé, y compris en cas de refus.

Créer le QR officiel d’un dépôt

Le paiement ne sera débité qu’après action du payeur dans le terminal officiel.