Paiement distant : cas particuliers

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 commission plateforme (cf. §5) */ ],
    "orderPlatformCommission": { /* OU commission numéraire fournie (cf. §5) */ }
  }
]

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).

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 de la règle platformCommission de l'entrée. La commission plateforme totale = somme des itemPlatformCommission + commission appliquée au reste.

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

4. Gestion des taxes

Les taxes (ex. TGC en Nouvelle-Calédonie) sont déclarées via taxDetail sur la commission ou les frais. Le champ isInclTaxAmount indique si un montant est TTC (défaut true) ou HT (les taxes sont alors ajoutées par-dessus). Les taxes sont calculées sur la base nette, puis arrondies au centime EUR ou au franc XPF.

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

5. Commissions plateforme (cascade 3 niveaux)

La commission que la plateforme perçoit sur ses marchands est résolue par priorité :

1. Numéraire fourni : orderPlatformCommission donné directement (montant TTC + détail) ; accepté tel quel, aucun calcul.
2. Règle de calcul : platformCommission (type PERCENTAGE ou FIXED, valeur, base TTC/HT, taxes) ; Mobupay calcule (brut par article → remises en 2 passes → taxes → arrondis → validation de cohérence).
3. Valeur par défaut (si ni l'un ni l'autre) : merchant_platform_links (couple plateforme-affilié) → platforms.default_platform_commission → merchant_configs.platform_commission → zéro.

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 indiquant qui supporte le remboursement. La somme des parts doit égaler le montant remboursé.

• Marchand absorbe : Marchand → Escrow → carte client.
• Plateforme absorbe : entrée pointant le compte plateforme (plt_*) : Plateforme → Escrow → carte client.
• Split : N entrées (marchand + plateforme), chacune débitée de sa part.

POST /api/v1/payments/{id}/refund
{
  "amount": 1500,
  "platformConfig": [
    { "merchantId": "mer_resto1", "amount": 800 },
    { "merchantId": "plt_needeat", "amount": 700 }
  ]
}

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).