MobupayMobupay
Chargement de vos clés API…

Le mode intégrateur

Faire ouvrir un compte à vos clients, émettre leurs paiements et prélever votre commission.

Plateforme, intégrateur direct ou indirect : trois questions pour choisir votre mode.

Le parcours

Votre logiciel invite un client. Il constitue seul son dossier, et vous autorise à accéder à son compte. À l'ouverture, Mobupay génère une clé de son compte que vous détenez : vous la retirez par l'API, vous encaissez avec, et vous prélevez s'il y a lieu votre commission sur chaque paiement.

  1. Vous ouvrez votre espace intégrateur vous-même, depuis Paramètres, Mes offres, ou dès la première étape de votre inscription (case « Devenir intégrateur »). Il est actif tout de suite, sans validation par Mobupay : vous réglez vous-même votre commission par défaut, et celle de chaque client, depuis Intégrateur, Clients.
  2. Vous émettez une clé d'intégrateur sk_int_test_ ou sk_int_live_, depuis Intégrateur, Clients, section Accès API.
  3. Vous invitez votre client : POST /api/v1/integrator/clients/invitations. Son redirectUrl, facultatif, est l'adresse de votre logiciel où votre client revient après avoir déposé son dossier : un bouton « Retourner vers » votre logiciel l'y ramène, et Mobupay y ajoute invitation_id, external_ref (si vous en avez donné une) et status, l'état du dossier. Cette adresse est en HTTPS ; avec une clé de test seulement, http://localhost est aussi accepté, pour essayer depuis votre poste. Dans prefill, la dénomination et l'enseigne sont proposées à votre client dans son dossier ; le numéro d'immatriculation vous est rendu, mais votre client le saisit lui-même. Inviter un client réel exige que votre propre compte de paiement soit ouvert, puisqu'il recevra vos commissions (409 INTEGRATOR_ACCOUNT_NOT_OPEN) ; une invitation simulée, en mode test, ne l'exige pas.
  4. Il ouvre le lien, constitue son dossier et coche l'autorisation donnée à votre logiciel. Vous suivez son état par integrator.client.onboarding.updated.
  5. Son compte ouvre : integrator.client.opened, puis integrator.client.key.available.
  6. Vous retirez le secret de la clé détenue, et vous encaissez avec, comme avec n'importe quelle clé marchande.
Un intégrateur n'instruit pas les dossiers : votre client constitue seul le sien, et vous n'en lisez que l'état. Pour constituer le dossier d'un client à sa place, voyez le module Agence.

Deux clés, deux usages

La clé d'intégrateur sk_int_* ne sert qu'aux routes /api/v1/integrator/* : inviter, suivre vos clients, retirer leurs clés, déclarer vos adresses de réception. Présentée ailleurs, elle reçoit 403 INTEGRATOR_KEY_OWN_ROUTES_ONLY. Elle n'encaisse jamais.

Chaque route de ce terrain exige une portée, que vous choisissez à la création de la clé : integrator.clients.read (vos clients et les clés que vous détenez, sans secret), integrator.keys.reveal (le secret d'une clé détenue, la plus sensible), integrator.keys.write (sa rotation), integrator.clients.write (vous détacher d'un client), integrator.invitations.read et integrator.invitations.write (vos invitations et la simulation), integrator.commissions.read, et webhooks.read / webhooks.write (vos adresses de réception). Une clé créée sans choix les porte toutes. Une portée manquante répond 403 INTEGRATOR_SCOPE_REQUIRED. Une clé créée avant le choix des portées garde les droits qu'elle avait.

La clé détenue est une clé sk_live_ du compte de votre client (sk_test_ pour un client simulé). Ses portées sont fixées par Mobupay : paiements, captures, remboursements, clients, moyens de paiement, adresses de réception et facturation, plus la lecture des boutiques quand votre client est une plateforme. Elle ne vire jamais les fonds de votre client : aucun virement, aucun bénéficiaire, aucune clé. Quand votre client est une plateforme, elle encaisse avec répartition entre ses partenaires, mais n'atteint pas ses partenaires eux-mêmes : les routes /api/v1/platform/* (dossiers, sous-marchands, sessions d'enrôlement) lui répondent 403 DELEGATION_FORBIDDEN.

Avec la même clé, vous créez les factures et les devis de votre client pour ses propres clients (/api/v1/billing/invoices, /api/v1/billing/quotes), s'il a activé le module Facturation ; sinon l'appel répond 403 BILLING_MODULE_NOT_ENABLED. Vous ne voyez que les documents créés par votre logiciel : une facture ou un devis fait par votre client sans vous est introuvable (404), et n'apparaît dans aucune liste. Une facture ne cite que vos fiches clients et vos ventes. Les listes d'envoi (recipient.billingEmails) et les réglages du module restent à votre client ; vous pouvez lire ses taux de taxe et son catalogue.

Votre client peut activer la Facturation avant d'avoir terminé son inscription. La clé détenue vous est alors remise dès cette activation, s'il vous a autorisé ; tant que son compte n'est pas ouvert, elle ne fait que facturer (factures, devis, fiches clients) et toute autre route répond 403 pour portée manquante. À l'ouverture du compte, la même clé encaisse, sans rotation, et vous recevez integrator.client.opened.

Votre client voit que votre logiciel est connecté à son compte, sans jamais voir la clé, et peut couper l'accès. La clé est alors refusée dès l'appel suivant, en 401 KEY_HOLDER_ACCESS_REVOKED, et vous recevez integrator.client.unlinked. Les paiements émis par la clé portent votre nom chez votre client.

Si Mobupay suspend votre espace intégrateur, toutes vos clés sont refusées, les vôtres comme celles que vous détenez, en 403 INTEGRATOR_SUSPENDED. Elles reviennent à la réactivation de l'espace, sans rien changer dans votre logiciel.

Retirer la clé de votre client

L'événement integrator.client.key.available annonce la clé sans son secret : un secret n'a rien à faire dans un webhook. Vous le retirez par un appel authentifié par votre clé d'intégrateur, du même environnement que la clé visée.

POST /api/v1/integrator/clients/{merchantId}/api-keys/{keyId}/reveal
Authorization: Bearer sk_int_live_…

{ "keyId": "key_…", "prefix": "sk_live_3f9a…", "environment": "live", "secret": "sk_live_…" }

Le secret est conservé chiffré : vous pouvez le retirer de nouveau, par l'API ou depuis Intégrateur, Clients après une revérification de votre identité. Chaque affichage est journalisé. Pour changer de secret, faites pivoter la clé (/rotate) : la nouvelle naît, l'ancienne est révoquée immédiatement, mettez donc votre stockage à jour dans la foulée.

Sans l'autorisation de votre client, aucune clé ne naît : le compte ouvre, mais consented vaut false et vous ne pouvez pas encaisser pour lui. Votre client peut vous autoriser plus tard, depuis Paramètres, Logiciels connectés : la clé naît alors et vous est annoncée par integrator.client.key.available.

Prélever votre commission

Sur un paiement que vous émettez avec la clé détenue, ajoutez order.integratorCommission, à côté de order.platformConfig et jamais dedans. Sa forme est celle de la commission d'une plateforme : PERCENTAGE en centièmes de pour-cent, ou FIXED en montant.

C'est la règle de calcul de la commande. Vous pouvez aussi fournir un montant pour la commande (order.orderIntegratorCommission), qui l'emporte sur la règle, et un montant par article (order.items[].itemIntegratorCommission), qui isole l'article. Le guide Commissions à plusieurs niveaux détaille comment ils se combinent.

  • type et value : PERCENTAGE avec 200 pour 2 %, ou FIXED avec un montant dans la devise de la commande (10 pour 10 XPF par paiement).
  • overInclTax, pour un pourcentage : calculé sur le montant taxes comprises (true, par défaut) ou hors taxes (false).
  • taxDetail : la taxe que vous facturez sur votre commission, par exemple la TGC. Elle est comprise dans le montant prélevé, et se retrouve sur vos factures de commission. Sans elle, votre commission ne porte aucune taxe.
POST /api/v1/payments/sessions
Authorization: Bearer sk_live_…   (la clé détenue de votre client)

{
  "order": {
    "reference": "CMD-1042",
    "amount": 12000,
    "currency": "XPF",
    "integratorCommission": {
      "type": "PERCENTAGE",
      "value": 200,
      "overInclTax": false,
      "taxDetail": [{ "id": "TGC6", "type": "PERCENTAGE", "value": 600 }]
    }
  },
  "redirectUrl": "https://app.votre-logiciel.nc/retour"
}
  • Avec une autre clé, le champ est refusé : 422 INTEGRATOR_COMMISSION_NOT_ALLOWED. Une valeur négative ou hors bornes (plus de 100 %, ou un montant fixe supérieur à la commande) rend 422 INTEGRATOR_COMMISSION_INVALID, et une commission que vous avez coupée dans votre espace 422 INTEGRATOR_COMMISSION_DISABLED.
  • Sans commission dans la commande, votre réglage s'applique : la commission de ce client, sinon votre commission par défaut. Vous réglez les deux depuis Intégrateur, Clients.
  • Vous fixez librement votre commission : Mobupay n'impose ni minimum ni maximum. Elle ne dépasse pas le montant de la commande.
  • L'assiette est ce que le compte de votre client reçoit au titre du paiement, pourboire exclu. Pour une plateforme cliente : ses commissions perçues et ses ventes propres.
  • Elle est servie la dernière : après la commission de plateforme, les frais Mobupay, le remboursement d'une avance de trésorerie et les sommes que votre client doit à Mobupay. Elle ne dépasse jamais ce qui reste du paiement.
  • Si le paiement ne suffit pas, le prélèvement est partiel ; le reste est repris sur les encaissements suivants que vous émettez pour ce client, jamais hors encaissement. Vous recevez integrator.commission.shortfall.
  • Sur un remboursement, votre commission vous reste acquise : on ne rembourse jamais avec l'argent d'un tiers. Quand votre client rembourse depuis son espace ou avec ses propres clés, il le fait à ses frais, et votre commission ne lui est pas rendue. Vous seul pouvez lui en rendre une part, quand votre logiciel rembourse pour lui avec la clé que vous détenez : tout, une partie (un pourcentage ou un montant) ou le prorata du montant remboursé (integratorCommissionRefund de POST /api/v1/payments/{id}/refund). Sans ce champ, rien n'est rendu. Vous recevez integrator.commission.restituted à chaque rendu. Si votre compte ne suffit pas, Mobupay avance la différence et vous en devez le remboursement. Un paiement entièrement financé par une plateforme n'en porte aucune.
  • Vous ne remboursez jamais vous-même : votre logiciel rembourse au nom de votre client, avec la clé que vous détenez pour lui ; votre clé sk_int_* ne le permet pas.

GET /api/v1/integrator/commissions rend, paiement par paiement, votre commission et rien d'autre : sa référence, celle du paiement d'origine, le dû taxes comprises avec sa taxe et son hors taxe, la règle appliquée, le prélevé, le reste et ce qui a été rendu. Le montant de la vente de votre client n'y figure pas : il lui appartient. Votre espace « Clients » montre les mêmes lignes, chacune avec son détail.

Si vous l'activez dans les paramètres de votre Facturation (« Facturation d'intégrateur »), une facture de vos commissions est émise chaque mois à chacun de vos clients, en votre nom. Elle est acquittée : les commissions ont été prélevées au fil de leurs encaissements.

Qui paie les frais Mobupay

C'est un réglage de votre boutique intégrateur, pas de chaque paiement. Deux choix :

  • Vos clients paient les frais Mobupay, chacun à son propre tarif. C'est le réglage par défaut.
  • Vous payez les frais Mobupay de vos clients, à votre tarif. Le volume de leurs paiements compte alors dans votre tranche.

Vous le choisissez à l'ouverture de la boutique, puis depuis la page Clients de votre espace ou avec PUT /api/v1/integrator/mobupay-fees-payer (clé sk_int_live_). Il reste modifiable tant que la boutique n'a ni client ni paiement, puis il est figé (409 MOBUPAY_FEES_PAYER_LOCKED). Pour faire payer l'autre partie, ouvrez une autre boutique intégrateur. Rien n'est à transmettre avec un paiement : le réglage de la boutique fait foi, et il est figé sur chaque paiement à sa création.

Quand vous payez les frais de vos clients :

  • Sur votre grille : les frais sont calculés avec le tarif de votre compte, et prélevés sur votre compte de paiement.
  • Après votre commission : votre commission sur ce même paiement couvre d'abord les frais. Si votre compte ne suffit pas, Mobupay avance la différence, et elle est reprise sur vos rentrées suivantes.
  • Tous les frais du paiement : ceux de l'encaissement, et ceux des événements qui le suivent (remboursement, annulation, authentification, contestation). Les frais Mobupay ne sont jamais rendus.
  • Votre client ne paie aucun frais Mobupay sur ce paiement : settlement.mobupayCommission vaut 0 et settlement.netAmount le montant capturé. Vous lisez vos frais sur vos commissions (mobupayFeesAmount, netAmount).

Combiner les modules

Les modules Plateforme, Intégrateur et Agence se cumulent sur un même compte. Voici ce que chaque combinaison permet, et ce qu'elle ne permet pas.

Votre client est une plateforme

Vous détenez la clé de la plateforme, et vous encaissez pour elle avec sa répartition habituelle. Le même paiement porte alors deux commissions : order.platformConfig (celle de la plateforme sur ses sous-marchands) et order.integratorCommission (la vôtre), côte à côte.

POST /api/v1/payments/sessions
Authorization: Bearer sk_test_…   (la clé détenue de la plateforme cliente)

{
  "order": {
    "reference": "CMD-2077",
    "amount": 5000,
    "currency": "XPF",
    "platformConfig": [
      {
        "merchantId": "mer_XXXX",
        "amount": 5000,
        "platformCommission": { "type": "PERCENTAGE", "value": 1000 }
      }
    ],
    "integratorCommission": { "type": "PERCENTAGE", "value": 200 }
  },
  "redirectUrl": "https://app.votre-logiciel.nc/retour"
}
  • Votre commission est prélevée sur le compte de la plateforme, jamais sur celui d'un sous-marchand. Son assiette est ce que la plateforme reçoit : ici, sa commission de 10 %.
  • Elle est servie après la commission de la plateforme, les frais Mobupay, le remboursement d'une avance de trésorerie et les sommes dues à Mobupay.
  • Vous ne voyez que la plateforme : ses sous-marchands n'apparaissent ni dans vos clients, ni dans vos commissions.

Votre client travaille aussi avec une agence

Si une agence et votre logiciel ont tous deux invité le même client, les deux relations naissent à la création de son dossier : l'agence reçoit la gestion que son mandat lui donne, vous recevez votre lien et, si le client vous y autorise, votre clé. Une autorisation donnée après l'ouverture du compte (Paramètres, Logiciels connectés) est réservée au titulaire : son agence ne peut pas la donner en son nom. Voyez le guide Agence.

Votre entreprise est elle-même une plateforme

Votre espace intégrateur appartient au compte de votre entreprise, et vos commissions d'intégrateur arrivent sur son compte de paiement Mobupay. Les deux activités restent distinctes : vos sous-marchands ne sont pas vos clients d'intégrateur, et réciproquement.

Ce qui n'est pas possible

  • Une commission d'intégrateur sur un paiement émis par une autre clé que celle que vous détenez pour ce client, y compris la clé d'une agence : 422 INTEGRATOR_COMMISSION_NOT_ALLOWED.
  • Plusieurs commissions d'intégrateur sur un même paiement : order.integratorCommission est un objet unique, et il n'existe pas de partage entre plusieurs logiciels.
  • Une commission d'intégrateur sur un paiement entièrement financé par une plateforme (net nul pour le porteur de carte).

Recevoir les événements

Déclarez une adresse de réception par POST /api/v1/integrator/webhooks. Elle appartient à votre espace et ne reçoit que les événements integrator.*. Chaque événement arrive signé, au format { id, type, createdAt, data }, comme les autres webhooks Mobupay (vérifier la signature).

integrator.invitation.created
Une invitation est créée.
integrator.invitation.expired
Une invitation a expiré sans qu'aucun dossier ne soit ouvert.
integrator.invitation.cancelled
Vous avez annulé une invitation.
integrator.client.onboarding.updated
L'état public du dossier a changé : lien ouvert, dossier commencé, déposé, en instruction, à corriger, ouvert, refusé.
integrator.client.opened
Le compte de paiement de votre client vient d'ouvrir. L'événement dit aussi s'il vous a autorisé à y accéder.
integrator.client.key.available
Une clé que vous détenez pour ce client est prête : à l'ouverture du compte, ou après un pivot. Elle porte l'identifiant et le préfixe, jamais le secret.
integrator.client.unlinked
Votre accès à ce compte est coupé, par votre client, par vous ou par Mobupay. Vos clés détenues sont révoquées.
integrator.commission.shortfall
Votre commission n'a été prélevée qu'en partie sur un paiement : le dû, le prélevé et le reste, repris sur les encaissements suivants.
integrator.commission.restituted
Vous avez rendu une part de votre commission à votre client, sur un remboursement fait par votre logiciel : le mode choisi, le rendu taxes comprises avec sa taxe et son hors taxe, la part retirée du reste dû, le cumul rendu et l'état de la commission. Jamais le montant de la vente ni celui du remboursement.

Les événements de paiement de votre client (payment.*) vous parviennent par les adresses que vous déclarez sur son compte, avec la clé détenue (POST /api/v1/webhooks). Votre client les voit comme gérées par votre logiciel, sans pouvoir les modifier.

Chacune de ces adresses a son propre secret de signature, rendu une seule fois à sa création : c'est lui qui vérifie ce que vous recevez. Le secret de signature du compte de votre client (GET /api/v1/webhooks/signing-secret) reste à votre client : la clé détenue reçoit 403 DELEGATION_FORBIDDEN sur cette route et sur sa rotation. Préférez donc ces adresses à un notificationUrl de paiement, dont la notification est signée avec le secret du compte.

Recetter sans conséquence

Avec une clé sk_int_test_, une invitation est simulée : aucun courriel ne part et rien n'est transmis à notre partenaire bancaire. Vous pilotez son avancement, état par état, et chaque transition émet les vraies notifications vers vos adresses de test.

À l'ouverture simulée, Mobupay crée un compte de test pour votre client et une clé sk_test_ que vous détenez, annoncée par integrator.client.key.available. Retirez-la comme en production, et encaissez avec en test : c'est ainsi que se recette tout le parcours, de l'invitation au premier paiement.

Simuler un enrôlement

Aucun courriel ne partira et aucun dossier réel ne naîtra.
L'invitation créée ici vit dans votre environnement de test. Elle produit de véritables notifications vers vos serveurs de test, et rien d'autre.

Collez une clé sk_int_test_ de votre espace intégrateur, ou connectez-vous pour choisir parmi les vôtres. Son secret n'est lisible qu'au moment de sa création, depuis Intégrateur, Clients, section Accès API : il est haché en base et ne se relit pas.

Les appels de la simulation

La console ne fait rien que votre outillage ne puisse faire. C'est le serveur qui dit, à chaque instant, quelles transitions sont possibles.

# Les transitions possibles depuis l'état courant, et la frise
GET  /api/v1/integrator/clients/invitations/{id}/simulation

# Faire avancer l'enrôlement d'un état
POST /api/v1/integrator/clients/invitations/{id}/simulation
     { "transition": "submit" }

# Effacer une simulation, avec le compte et la clé qu'elle a créés
DELETE /api/v1/integrator/clients/invitations/{id}

La réponse d'une transition vers l'ouverture porte merchantId et heldKey (identifiant et préfixe de la clé détenue). Une transition impossible est refusée en 409 ILLEGAL_TRANSITION avec la liste de celles qui sont acceptées ; en rejouer une déjà faite rend 200 sans rien réémettre.