MobupayMobupay
Chargement de vos clés API…

Paiement distant : cas particuliers

Cette page regroupe les scénarios avancés du paiement distant en mode plateforme : déclaration de platformConfig, remises plateforme, articles facturés par la plateforme, taxes, commissions, remboursements et financement plateforme. Tous les montants sont exprimés dans la devise d'origine de la commande (order.currency) ; Mobupay convertit en interne en centimes EUR pour la répartition.

1. L'objet platformConfig

platformConfig est un tableau d'entrées, une par marchand bénéficiaire. Il déclare la répartition d'un paiement plateforme.

"platformConfig": [
  {
    "merchantId": "mer_resto1",      // marchand bénéficiaire (ou plt_* pour la plateforme)
    "amount": 3000,                   // part brute de ce marchand (devise d'origine)
    "items": [                        // détail des articles (optionnel mais recommandé)
      {
        "product": "Menu", "unitPrice": 1500, "quantity": 2,
        "itemPlatformCommission": { /* commission spécifique à cet article (cf. §3) */ }
      }
    ],
    "platformCommission": { /* règle de calcul du reste de la part (cf. §5) */ },
    "orderPlatformCommission": { /* montant fourni pour le reste, l'emporte sur la règle (cf. §5) */ }
  }
]

Règle de cohérence

La somme des platformConfig[].amount doit égaler order.amount, montant brut avant la remise prise en charge par la plateforme (order.discount, cf. §2).

2. Remises prises en charge par la plateforme

Lorsqu'une plateforme finance une remise (code promo maison), le client ne paie que le NET sur sa carte, et la plateforme abonde le complément pour que le marchand perçoive le montant brut. La carte autorise et affiche le net (RG_PAY_DISCOUNT_NET_01).

"order": { "amount": 3000, "discount": 500, "currency": "XPF" }
// Le client paie 2500 (net). La plateforme abonde 500.
// Flux : Client → 2500 → Escrow ; Plateforme → 500 → Escrow ;
//        Escrow → Marchand 3000 (brut).

Promotion ajoutée à la capture, au-dessus de l'autorisation (top-up) : en capture MANUAL, si seul le net client a été autorisé à la commande (détail inconnu à l'autorisation), l'order.amount défini à la capture peut dépasser le montant autorisé, à condition que la remise plateforme couvre l'excédent, pourboires inclus : (order.amount − order.discount) + Σ tips ≤ autorisé. La carte n'est jamais débitée au-delà de l'empreinte : le montant EUR débité est exactement l'EUR déjà autorisé (aucune dérive d'arrondi XPF→EUR, le complément plateforme absorbe la conversion). Sinon : 400 CAPTURE_AMOUNT_EXCEEDS_AUTHORIZED_UNFUNDED.

// Autorisé à la commande : 2595 XPF (net client, sans détail).
// À la capture, distribution du brut 2940 :
POST /payments/{id}/capture
{ "amountCents": 2595,                       // net débité = autorisé (optionnel)
  "order": { "amount": 2940, "discount": 345,
    "platformConfig": [
      { "merchantId": "mer_restaurant", "amount": 2300, "platformCommission": {...} },
      { "merchantId": "mer_livreur",   "amount": 640 } ] } }
// Carte : 2595 (= EUR autorisé, au centime près) ; Plateforme → 345 → Escrow ;
// Escrow → Restaurant 2300 + Livreur 640. Le webhook payment.captured détaille
// grossAmount / cardNetAmount / platformFundedDiscount / tipsTotal.

Répartir une remise entre le sous-marchand et la plateforme

Chaque part de la remise se déclare à un endroit distinct :

  • la part portée par le sous-marchand se retire de son platformConfig[].amount ; order.amount reste égal à la somme des platformConfig[].amount ;
  • la part portée par la plateforme se déclare dans order.discount : la carte est débitée de order.amount − order.discount, et la plateforme abonde la différence.
// Panier 3000 XPF, remise 500 : 200 portés par le sous-marchand, 300 par la plateforme.
"order": { "amount": 2800, "discount": 300, "currency": "XPF",
  "platformConfig": [ { "merchantId": "mer_resto1", "amount": 2800 } ] }
// Le client paie 2500. La plateforme abonde 300.
// Le sous-marchand reçoit 2800.

La commission plateforme en pourcentage se calcule sur platformConfig[].amount (2 800 dans l'exemple) : la part de remise du sous-marchand réduit l'assiette, celle de la plateforme ne la réduit pas. Le champ platformConfig[].discount est une remise sur la commission plateforme due pour ce sous-marchand : il ne modifie ni le montant débité ni la part versée.

Au remboursement, le montant remboursable est plafonné à ce que la carte a payé (2 500 dans l'exemple) : l'abondement de la plateforme n'est pas restitué au client.

3. Articles facturés par la plateforme

Un article peut porter une commission spécifique via itemPlatformCommission (ex. frais de service sur un plat précis). Les articles sans commission propre relèvent du montant de commande orderPlatformCommission de l'entrée s'il est fourni, sinon de sa règle platformCommission. La commission plateforme totale = somme des itemPlatformCommission + commission du reste.

"items": [
  { "product": "Pizza", "unitPrice": 1500, "quantity": 1,
    "itemPlatformCommission": { "commissionAmount": 50, "taxAmount": 8 } },
  { "product": "Coca", "unitPrice": 500, "quantity": 1 }   // -> montant de commande, sinon règle de l'entrée
]

4. Gestion des taxes

Les taxes (par exemple la TGC en Nouvelle-Calédonie) se déclarent par taxDetail, à deux endroits distincts : sur les articles et la commande, pour la taxe de la vente ; sur une commission (platformCommission.taxDetail), pour la taxe que la plateforme facture sur sa commission. Les taxes sont calculées sur la base nette, puis arrondies au centime EUR ou au franc XPF.

La taxe d'une commission s'ajoute toujours à son montant : une commission de 1 000 avec une TGC à 6 % prélève 1 060 au sous-marchand.

Le champ isInclTaxAmount, à la racine de la requête, est le drapeau de la commande, pas celui de la commission. Avec true (par défaut), les prix des articles et order.amount sont taxes comprises, et la taxe en est extraite. Avec false, ils sont hors taxes : la taxe est calculée en plus des prix et portée dans order.taxAmount, mais elle n'est pas ajoutée au montant débité, qui reste order.amount (plus le pourboire).

"taxDetail": [ { "id": "TGC6", "type": "PERCENTAGE", "value": 600 } ]
// value en centièmes de % : 600 = 6,00 %

5. Commissions plateforme (plusieurs niveaux)

La commission que la plateforme perçoit sur ses marchands se compose ainsi. Les articles qui portent leur propre itemPlatformCommission sont isolés (§3) ; le reste de la part est couvert par :

  1. Montant fourni par commande : orderPlatformCommission donné directement (montant TTC + détail) ; accepté tel quel, aucun calcul. Il l'emporte sur la règle.
  2. Règle de calcul : platformCommission (type PERCENTAGE ou FIXED, valeur, assiette d'un pourcentage par overInclTax, taxes comprises par défaut, taxes de la commission) ; Mobupay calcule (brut par article → remises en 2 passes → taxes → arrondis → validation de cohérence). Avec overInclTax: false, l'assiette hors taxes est déduite des taxes déclarées à la racine de la commande (order.taxDetail) ; sans elles, l'assiette reste la part.
  3. Valeur par défaut (si la commande ne porte aucune commission, ni article, ni montant, ni règle) : merchant_platform_links (couple plateforme-affilié) → platforms.default_platform_commission → merchant_configs.platform_commission → zéro.

Combinaisons

Tout se combine sur une même entrée. Montant fourni et règle ensemble : le montant l'emporte, sans erreur. Des articles à montant fourni sans montant ni règle de commande laissent le reste sans commission. Le guide Commissions à plusieurs niveaux en donne un exemple chiffré.

6. Commission Mobupay

La commission Mobupay (objet orderPaymentFees, champ detailedFees) est composée de 3 tables fusionnées :

  • tarification : tarif de base par événement/sous-type/devise/pays.
  • payin_card_option : supplément selon le type de carte.
  • remote_payin_option : supplément par événement (capture, remboursement, annulation, 3DS).

Sur un paiement plateforme multi-marchand, la commission Mobupay est prélevée une seule fois sur le montant total, après la répartition (jamais par sous-marchand). Un remboursement enrichit l'orderPaymentFees du paiement initial (pas de nouvel objet).

7. Remboursements : 3 modes (plateforme)

POST /payments/{id}/refund accepte un platformConfig qui désigne qui finance le remboursement : un tableau d'entrées { merchantId, amount }, comme à la commande. La somme des parts doit égaler le montant remboursé. Sur un paiement capturé dont la commande est répartie entre plusieurs marchands (la plateforme et au moins un sous-marchand), il est obligatoire : sans lui, la demande est refusée (REFUND_PLATFORM_CONFIG_REQUIRED). Cette règle vaut que la répartition ait déjà été versée ou non. Une annulation partielle d'un paiement non capturé l'exige aussi ; seule son annulation totale en est dispensée, aucun compte n'étant alors débité.

Un sous-marchand désigné comme financeur n'est débité qu'après avoir reçu sa part du paiement. Si le remboursement est traité avant la répartition, son débit attend celle-ci. Le compte de la plateforme, lui, est débité au traitement du remboursement.

Pour une commande dont la répartition a été transmise sous l'ancienne forme objet ({ segmentation } ou { merchants }), cette exigence s'applique à partir du 05/11/2026. Jusque-là, une demande sans platformConfig est acceptée et imputée en totalité sur le compte de la plateforme.

  • Marchand absorbe : une entrée portant le merchantId du marchand : Marchand → Escrow → carte client.
  • Plateforme absorbe : une entrée portant le merchantId de la plateforme elle-même : Plateforme → Escrow → carte client.
  • Partage : plusieurs entrées (marchands et plateforme), chacune débitée de sa part.
POST /api/v1/payments/{id}/refund
{
  "amountCents": 1500,                       // devise d'origine du paiement
  "platformConfig": [
    { "merchantId": "mer_resto1", "amount": 800 },
    { "merchantId": "mer_plateforme", "amount": 700 }  // la plateforme, par son merchantId
  ]
}

L'ancienne forme objet { platformAccountId, segmentation } est dépréciée : elle reste acceptée jusqu'au 05/11/2026, puis sera refusée.

8. Multimarchand : répartitions parallèles

Un paiement réparti entre N marchands génère N répartitions (Escrow → marchand i) puis N commissions plateforme (une par marchand) et une commission Mobupay unique sur le total. La répartition est faite en centimes EUR par la méthode du plus grand reste, garantissant que la somme des parts égale exactement le total (invariant compte centralisateur = 0).

9. Paiement net carte = 0 (financé par la plateforme)

En mode plateforme, si la commande est intégralement couverte par une remise plateforme (order.amount > 0 et order.discount = order.amount, sans pourboire), aucune carte n'est requise. Mobupay crée le paiement en authorized(fundingMode: 'platform_funded') et la checkoutUrl redirige immédiatement vers redirectUrl. La répartition aux marchands a lieu à la capture, financée par la plateforme. Un montant nul (order.amount = 0) est refusé. Le remboursement d'un tel paiement est total uniquement (le net carte est nul).