Splits marketplace

Pour les plateformes qui encaissent pour le compte de vendeurs tiers (marketplaces, VTC, livraison), les splits répartissent une transaction entrante entre plusieurs marchands bénéficiaires.

Modèle

• Une transaction parent est encaissée par le marchand plateforme (vous).
• Chaque ligne payment_split crédite un marchand bénéficiaire d'une partie du montant.
• La répartition effective sur les soldes des bénéficiaires a lieu lors du cycle de reversement (le lendemain par défaut).

Créer des splits

POST/v1/payments/{transaction_id}/splits

{
  "splits": [
    {
      "beneficiary_merchant_id": "uuid-vendor-A",
      "amount": "60.00",
      "description": "Commande #ORD-001 — Vendeur A"
    },
    {
      "beneficiary_merchant_id": "uuid-vendor-B",
      "amount": "75.00"
    }
  ]
}

Ici, la transaction parente est de Le 150.00 : la plateforme conserve Le 15.00.

Invariants

• La somme des amount ne doit pas dépasser le montant de la transaction parente.
• Chaque beneficiary_merchant_id doit être un marchand actif.
• Les splits sont immuables une fois créés. Pour en corriger un, annulez-le par une écriture compensatoire, puis recréez-le.
• Refusé si la transaction est dans un état final défavorable (cancelled, expired).
• Sûr en concurrence : deux appels POST/v1/payments/{id}/splits parallèles sur le même parent sont sérialisés. Un appel concurrent qui dépasserait le total est rejeté avec 422 split_rejected, même si chaque appel seul serait passé.

Réponse 201

{
  "data": [
    {
      "id": "...",
      "object": "payment_split",
      "transaction_id": "...",
      "beneficiary_merchant_id": "uuid-vendor-A",
      "amount": "60.00",
      "currency": "SLE",
      "is_settled": false,
      "settled_at": null,
      "created_at": "2026-10-21T09:41:00+00:00"
    },
    ...
  ]
}

Lister les splits d'une transaction

GET/v1/payments/{transaction_id}/splits

Ce que conserve la plateforme

platform_keeps = transaction.amount − Σ(split.amount)

Vous pouvez répartir jusqu'à 100 % du montant (la plateforme ne garde rien) ou conserver une marge.

Reversement

Quand la transaction atteint success, les splits non reversés créditent les soldes des bénéficiaires. Le virement bancaire effectif suit le cycle configuré sur leur offre (quotidien/hebdomadaire).

Usages typiques

Plateforme	Schéma
Marketplace de produits	1 paiement client → N splits vendeurs + 1 commission plateforme
VTC	1 course → 1 split chauffeur (80 %) + 1 commission plateforme (20 %)
Location	1 loyer → 1 split propriétaire (90 %) + 1 commission
Financement participatif	1 don → 1 split bénéficiaire + 1 frais de service

Erreurs

Code	HTTP	Cause
split_rejected	422	Total supérieur au montant de la transaction, bénéficiaire inactif, transaction finale
transaction_not_found	404	Identifiant inconnu pour ce marchand