Paiement distant : Plateforme multimarchand
Cas d'une plateforme qui agrège plusieurs commerçants (ex. une plateforme de commande). Le contrat monétique est rattaché à un compte centralisateur (séquestre). Un paiement unique est encaissé sur ce compte, puis réparti vers les marchands sous-jacents, avant que la plateforme et Mobupay ne prélèvent leurs commissions. La répartition est déclarée via l'objet platformConfig.
Requête : un marchand
On ajoute platformConfig : un tableau d'entrées, une par marchand bénéficiaire. La somme des amount doit égaler order.amount.
POST /api/v1/payments/sessions
Authorization: Bearer sk_test_CLE_PLATEFORME
{
"order": {
"reference": "CMD-100",
"amount": 3000,
"currency": "XPF"
},
"platformConfig": [
{
"merchantId": "mer_resto1",
"amount": 3000,
"items": [{ "product": "Menu", "unitPrice": 3000, "quantity": 1 }]
}
],
"redirectUrl": "https://example.com/return",
"notificationUrl": "https://example.com/webhook"
}Requête : plusieurs marchands (panier multi-vendeur)
Un même paiement peut être réparti entre plusieurs marchands d'une même plateforme.
"platformConfig": [
{ "merchantId": "mer_resto1", "amount": 1000, "items": [ ... ] },
{ "merchantId": "mer_resto2", "amount": 1500, "items": [ ... ] },
{ "merchantId": "mer_resto3", "amount": 500, "items": [ ... ] }
]
// order.amount = 3000 = 1000 + 1500 + 500Flux des fonds
- Le client paie le total sur la page hébergée Mobupay.
- Les fonds sont encaissés sur le compte centralisateur (escrow).
- Pour chaque entrée de
platformConfig:Escrow → Compte marchand(montant brut). - Commission plateforme, par marchand :
Compte marchand → Compte plateforme. - Commission Mobupay, une seule fois sur le total :
Compte plateforme → Commission Mobupay. - Invariant : après répartition, le compte centralisateur revient à zéro.
Schéma : EXT → Escrow → Marchand(s) → Plateforme → Commission Mobupay.
Qui paie les frais
En mode plateforme, c'est la plateforme qui supporte la commission Mobupay (prélevée sur son compte). La plateforme perçoit par ailleurs sa propre commission auprès de ses marchands sous-jacents.
Suivre l'enrôlement d'un partenaire
Avant de pouvoir désigner un marchand dans platformConfig, il faut l'enrôler. Vous émettez une invitation, votre partenaire constitue son dossier, Mobupay et son partenaire bancaire l'instruisent, puis le compte ouvre. Ce parcours dure des jours, parfois des semaines, et vous devez pouvoir le suivre.
Chaque invitation porte un enrollmentStatus, lisible sur GET /platform/onboarding-sessions/{id} et poussé à chaque changement par l'événement merchant.onboarding.updated :
INVITED le lien est parti, jamais ouvert
LINK_OPENED lien ouvert, dossier pas commencé
DRAFT dossier en cours de constitution
SUBMITTED dossier déposé, contrôles en cours
IN_REVIEW en instruction chez Mobupay
CORRECTION_REQUESTED des corrections sont attendues de votre partenaire
OPENED compte ouvert, vous pouvez encaisser pour lui
REFUSED fin de parcours
SUSPENDED compte ouvert puis suspendu
EXPIRED invitation périmée sans dossier ouvert
CANCELLED invitation annuléeLe champ actionRequired répond directement à la question utile : sub_merchant (relancez votre partenaire), mobupay (patientez, rien à faire), platform (à vous d'agir), none.
Pour renvoyer un partenaire à l'étape exacte où il s'est arrêté, demandez un lien de reprise. Il repart de son dossier en cours, jamais d'un formulaire vierge :
POST /api/v1/platform/onboarding-sessions/mcs_.../resume-link
Authorization: Bearer sk_live_CLE_PLATEFORME
{ "expiresInHours": 72, "sendEmail": true }
→ 200
{
"url": "https://app.mobupay.nc/checkout/merchant/mcs_...?t=...",
"expiresAt": "2026-08-21T10:00:00Z",
"enrollmentStatus": "CORRECTION_REQUESTED",
"resumeStep": "documents",
"emailSent": true
}Le lien précédent cesse aussitôt de fonctionner : un seul lien de reprise circule à la fois. Une fois le compte ouvert, retrouvez vos partenaires par GET /platform/merchants, qui porte le merchantId à citer dans platformConfig.
Aller plus loin