Paiements fractionnés

Deux fonctionnalités sans rapport utilisent le terme split. Les personnes qui viennent d'une autre plateforme de paiement recherchent généralement une troisième fonctionnalité qui n'existe pas ici. Cette page définit clairement leurs limites.

Paiement en plusieurs fois

Cette fonctionnalité n'a aucun rapport avec les marketplaces. Le même payeur règle un seul paiement en deux, trois ou quatre tranches, débitées successivement.

L'appel débite le paiement comme POST /payments/{id} et prend donc les mêmes channel et data. Envoyez split_count pour obtenir des tranches égales, ou split_amounts pour des tranches différentes. Ces deux champs sont mutuellement exclusifs. La somme de split_amounts doit être égale à ce que paie le payeur : le amount du paiement, ou son amount_total quand le payeur supporte les frais.

curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx/splits \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "cm.mtn",
    "data": { "phone": "+237670000000" },
    "split_count": 3
  }'

split_count accepte uniquement les valeurs 2, 3 ou 4. Pour obtenir des tranches inégales, envoyez vous-même les montants.

curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx/splits \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "cm.mtn",
    "data": { "phone": "+237670000000" },
    "split_amounts": [4000, 3000, 3000],
    "split_currency": "XAF"
  }'

Envoyez entre deux et quatre valeurs, chacune au moins égale à 0,01 et dans la précision de la devise : des francs entiers en XAF et en XOF. Un payeur, un paiement, plusieurs débits.

Ce que fait chaque appel

Le premier appel fixe le plan et débite la première tranche. Chaque appel suivant débite la suivante : envoyez-le avec les mêmes channel et data, sans split_count ni split_amounts, ou avec le même plan. Un plan différent est refusé avec un 422. Dès qu'un paiement a un plan, tout débit de ce paiement, POST /payments/{id} ou la page de paiement, prend la tranche suivante, jamais le montant entier.

Chaque réponse porte la tranche dans transaction.split : son id, split_number, total_splits, amount et status. Les tranches égales sont en unités entières, et la dernière prend le reste : 10 000 XAF en trois font 3 333, 3 333 et 3 334.

Une tranche refusée est débitée de nouveau par l'appel suivant. Les tranches déjà payées le restent : amount_collected est leur total, et le paiement ne revient jamais à pending une fois qu'une somme a été encaissée.

Quand l'argent est à vous

Chaque tranche est à vous dès qu'elle passe : elle est créditée sur votre solde aussitôt, sous la retenue habituelle, et paie sa part des frais Wajub à ce moment-là, en live comme en sandbox. Quand le payeur prend les frais à sa charge, vous êtes crédité de votre part de chaque tranche et les tranches s'additionnent jusqu'à amount. Le paiement passe à succeeded avec sa dernière tranche, et n'expire pas tant qu'il est partial. Chaque tranche envoie payment.split.processing, puis payment.split.succeeded ou payment.split.failed ; payment.succeeded arrive une fois, avec la dernière. Les événements de tranche décrivent le contenu.

Quand le payeur cesse de payer

Rien ne clôt un paiement partial de lui-même. C'est vous qui décidez, avec POST /payments/{id}/close et un outcome :

payment.succeeded est envoyé une fois, comme pour un paiement réglé en entier ; les remboursements et le statut refunded se mesurent ensuite à ce qui a été encaissé. Une clôture pendant qu'une tranche attend le payeur répond 409 payment_in_progress, et DELETE /payments/{id} refuse un paiement dont des tranches sont déjà payées (409 payment_partly_paid) : clôturez-le plutôt.

Chaque tranche doit tenir sous le plafond par transaction du Mobile Money. Un débit unique au-dessus est refusé avec un 422, en live comme en sandbox : rien ne fractionne un paiement de lui-même, les tranches sont votre choix. Un paiement réglé en tranches est remboursé par l'équipe Wajub plutôt qu'automatiquement, car chaque tranche peut provenir d'un autre numéro.

Tarification par connexion

Cette fonctionnalité concerne les marketplaces. Un paiement attribué à une connexion appartient au marchand correspondant. Votre plateforme reçoit la commission configurée sur cette connexion.

curl https://api.wajub.com/payments \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "XAF",
    "customer": { "email": "[email protected]" }
  }'

Vous ne pouvez pas remplacer la commission pour une requête particulière. Elle provient des règles associées à la connexion, figées lors de l'acceptation du marchand. Le payload ne contient aucun champ de frais. Capacités du compte explique comment la règle est choisie et limitée.

La fonctionnalité qui n'existe pas

Un panier avec plusieurs vendeurs nécessite donc plusieurs paiements, un par vendeur et chacun avec son propre en-tête.

La dernière ligne vous sera utile plus tard. Le rapprochement d'un panier après son traitement est uniquement possible si tous ses paiements contiennent le même identifiant de votre système.

Le payout d'un marchand constitue encore une autre opération

Aucune de ces fonctionnalités ne transfère de l'argent vers le compte bancaire ou le portefeuille d'un marchand. Les fonds d'un paiement connecté sont réglés sur le propre solde Wajub du marchand, et la façon dont ils en sortent dépend du mode : un marchand direct retire lui-même, un marchand lite est payé automatiquement par Wajub, et une marketplace relay paie ses vendeurs par lots. Les trois sont décrits dans Payer les vendeurs. Pendant ce temps, votre commission a déjà été créditée sur le solde de votre plateforme sans aucun appel de votre part, retirable dès que la vente dont elle vient a passé sa rétention.