Plateforme · Guides de recettes
Ventiler un panier entre plusieurs marchands
Un débit carte, plusieurs bénéficiaires, une commission plateforme. L'ordre des montants compte.
1. Vérifier le contrat Plateforme
Sans contrat Platform actif, tous les endpoints platform/* répondent 403 PLATFORM_REQUIRED. Le contrat s'obtient auprès de Mobupay, il ne s'active pas par API.
2. Autoriser en capture manuelle
Créez la session en MANUAL. La ventilation définitive n'est presque jamais connue à la commande : c'est à la capture qu'elle l'est.
{
"order": { "reference": "CMD-2026-0142", "amount": 5000, "currency": "XPF" },
"captureMode": "MANUAL",
"redirectUrl": "https://example.com/return",
"notificationUrl": "https://example.com/webhook"
}3. Décrire la ventilation
order.platformConfig liste les bénéficiaires. La somme des amount doit être égale à order.amount : le partage couvre la totalité de la commande, jamais une partie.
"platformConfig": [
{ "merchantId": "mer_restaurant", "amount": 4000,
"platformCommission": { "type": "PERCENTAGE", "value": 2500 } },
{ "merchantId": "mer_livreur", "amount": 1000 }
]4. Sortir le pourboire du montant
Un pourboire se déclare par tips sur l'entrée du bénéficiaire qui le reçoit, et se retire de order.amount. Le brut passe alors sous le montant autorisé : c'est normal, la couverture s'apprécie sur le débit carte, order.amount − order.discount + Σ tips.
N'ajoutez jamais le pourboire à l'amount d'une entrée. La somme versée serait la même, mais votre commission plateforme se calculerait dessus, alors qu'un pourboire n'est pas commissionné.
5. Capturer
La capture accepte l'order complet. Un sous-objet fourni remplace le sous-objet entier : il n'y a pas de fusion champ par champ.
{
"order": {
"amount": 5000,
"platformConfig": [
{ "merchantId": "mer_restaurant", "amount": 4000,
"platformCommission": { "type": "PERCENTAGE", "value": 2500 } },
{ "merchantId": "mer_livreur", "amount": 1000 }
]
}
}6. Lire la redistribution
La réponse porte settlement (commission Mobupay et net de la transaction) et platformDistribution : par sous-marchand, le brut versé, la commission plateforme prélevée et le net versé. C'est la seule vue qui dit ce que chacun a réellement reçu.
7. Capturer moins que l'autorisé, en le disant
Une commande partiellement livrée se capture pour moins, à condition de redéfinir le détail : order.amount réduit et le platformConfig correspondant, dont les montants totalisent ce nouvel amount.
Un order.amount simplement plus petit, sans détail, est refusé : 400 CAPTURE_AMOUNT_BELOW_AUTHORIZED. Une baisse doit être justifiée, jamais muette.