Chargement de vos clés API…

Le mode intégrateur

Faire ouvrir un compte à vos clients, encaisser en leur nom et prélever votre commission.

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.

Mobupay valide votre espace intégrateur, demandé dès la première étape de votre inscription (case « Devenir intégrateur ») ou ouvert par Mobupay sur demande, et règle votre commission par défaut.
Vous émettez une clé d'intégrateur sk_int_test_ ou sk_int_live_, depuis Intégrateur, Clients, section Accès API.
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.
Il ouvre le lien, constitue son dossier et coche l'autorisation donnée à votre logiciel. Vous suivez son état par integrator.client.onboarding.updated.
Son compte ouvre : integrator.client.opened, puis integrator.client.key.available.
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 et adresses de réception, 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.

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.

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 rend 422 INTEGRATOR_COMMISSION_INVALID, et une commission que Mobupay n'a pas ouverte pour votre espace 422 INTEGRATOR_COMMISSION_DISABLED.
Absent, la commission par défaut s'applique : celle convenue pour ce client, sinon celle de votre espace. Toutes deux sont réglées par Mobupay.
Vous pouvez demander moins que la commission convenue, jamais plus. La comparaison porte sur le montant calculé sur la commande : un pourcentage et un montant fixe se comparent en montant. Au-delà, ou si aucune commission n'est convenue pour ce client, le champ est refusé : 422 INTEGRATOR_COMMISSION_ABOVE_AGREED. Au prélèvement, la commission reste plafonnée à celle convenue.
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.

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.

Clé employée

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.

Adresse du contact factice

Nom de l'enseigne

Référence externe

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.