Litiges

Un litige, c'est un payeur, ou son réseau de carte, qui signale à Wajub qu'un paiement pose problème. Il porte sur un seul paiement et se termine de l'une de deux façons : soit vous gardez l'argent, soit il repart et votre solde est débité.

Contrairement à un remboursement, ce n'est pas vous qui ouvrez un litige, et vous ne pouvez pas en créer un par l'API. Votre rôle est d'y répondre.

D'où vient un litige

Un litige vous parvient de l'un de deux endroits.

Le payeur l'ouvre depuis Pocket, le portefeuille Wajub où il retrouve les paiements qu'il a effectués. Il choisit un motif, décrit le problème, et cette description devient le premier message du fil de discussion du litige.

Un litige ouvert depuis Pocket porte sur le montant total du paiement, et porte un due_date avant lequel répondre, sept jours après son ouverture.

Le prestataire signale une rétrofacturation. Quand un réseau de carte ou un prestataire notifie une rétrofacturation sur l'un de vos paiements, Wajub ouvre un litige pour elle. Il porte la référence du prestataire dans provider_reference, son code de motif dans reason, et le montant que le prestataire conteste, qui peut être inférieur au paiement. Il porte aussi un due_date : l'échéance du prestataire quand il en envoie une, sept jours après l'ouverture sinon.

Dans les deux cas, un paiement n'a qu'un seul litige en cours à la fois. Un second avis pour le même dossier n'ouvre pas de second litige.

Les états d'un litige

Un litige arrive en open. L'envoi de justificatifs le fait passer de lui-même en under_review, vous ne réglez pas ce statut vous-même. Depuis l'un ou l'autre de ces deux états, il peut se terminer en won ou en lost, et les deux sont définitifs.

C'est Wajub qui tranche. Aucun endpoint ne vous permet de vous déclarer gagnant ; ce que vous pouvez faire, c'est présenter les justificatifs à ceux qui décident, ou concéder.

Répondre avec des justificatifs

C'est cette étape qui décide de l'issue, et elle mérite d'être soignée. Chaque justificatif est classé sous un type, et vous pouvez faire plusieurs appels pour constituer votre dossier.

Le type est un emplacement, pas une étiquette. Envoyez deux appels avec proof_of_delivery et le second remplace le premier, il ne s'y ajoute pas. Utilisez un type différent pour chaque justificatif distinct, et mettez tout ce que vous voulez dire sur un justificatif dans cet unique appel.

Envoyez un texte, un fichier, ou les deux : un appel sans l'un ni l'autre répond 422, et le litige reste où il était. Sans fichier, le justificatif est enregistré sous la forme de votre seul texte : evidence.proof_of_delivery est alors une chaîne et non un objet. Un fichier est enregistré sous un nom à lui, avec l'extension de son contenu ; le nom que vous lui aviez donné revient dans file_name.

Les fichiers sont privés : aucune adresse ne les ouvre d'elle-même. Chaque réponse de l'API qui renvoie le litige donne à chaque fichier, justificatifs comme pièces jointes des messages, une url, un lien signé valable 30 minutes. Passé ce délai, relisez le litige pour en obtenir un nouveau. Un webhook porte file_path sans lien, car il est conservé et renvoyé bien après l'expiration d'un lien.

Comme un fichier est en jeu, il s'agit d'un envoi de formulaire et non d'un corps JSON.

curl https://api.wajub.com/disputes/dsp_hrgUOE225KMKULRQqYvlh/submit-evidence \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -F "evidence_type=proof_of_delivery" \
  -F "evidence_text=Delivered 12 Sept, signed for by the customer." \
  -F "evidence_file=@/path/to/delivery-note.pdf"

L'appel répond 200 OK avec le litige dans son état actuel, déjà passé en under_review, et vos justificatifs regroupés sous evidence.

Les justificatifs ne peuvent être déposés que tant que le litige est open ou under_review. Une fois en won ou lost, l'appel répond 422 et le dossier est clos.

Concéder, et un appel qui ne fait pas ce que son nom laisse croire

Si le payeur a raison, concédez tôt plutôt que de laisser traîner.

L'acceptation prend un merchant_response facultatif, 2 000 caractères maximum, enregistré sur le litige. Elle passe le litige en lost immédiatement, sans retour possible, et rend l'argent au payeur : Wajub crée un remboursement du montant contesté, plafonné à ce qui reste remboursable sur le paiement.

Ce remboursement porte le motif customer_complaint et le motif du litige dans metadata.dispute_reason, et il rend au payeur tout ce qu'il a payé pour ce montant, y compris des frais qu'il aurait payés en plus. Si le remboursement ne peut pas être créé, l'appel échoue et le litige reste dans son état.

Trois cas ne créent aucun remboursement, et le litige finit quand même lost :

• Une rétrofacturation. La banque du payeur lui a déjà rendu l'argent et le prestataire le reprend à Wajub : un remboursement paierait le payeur deux fois.
• Plus rien à rembourser. Des remboursements antérieurs ont déjà rendu tout le paiement.
• Un litige dans une autre devise que son paiement. Il n'y a pas de montant à rembourser dans la devise du paiement.

Échanger avec le payeur

Un litige porte un fil de messages, ouvert par la description du payeur lui-même. Vous pouvez y répondre.

Les messages prennent content, obligatoire et limité à 5 000 caractères, et un tableau attachments facultatif de fichiers soumis aux mêmes contraintes que les justificatifs. Chaque pièce jointe revient avec file_name, file_path et la même url valable 30 minutes. POST /disputes/{id}/send-message est un alias du même appel. Vos messages sont enregistrés avec un sender_type à merchant, ceux du payeur avec customer, et le fil complet est renvoyé lorsque vous récupérez le litige. Le fil reste ouvert après l'issue : un message sur un litige déjà won ou lost est accepté et enregistré, mais ne change rien au résultat.

Consulter les litiges

Récupérer un litige le renvoie avec sa transaction, son client et son fil de messages complet.

Au-delà des champs évidents, un litige porte la description du payeur, votre merchant_response, les justificatifs que vous avez déposés dans evidence, resolved_at une fois terminé, et metadata.

Ce que coûte une perte

Sur un paiement encaissé par le prestataire propre à Wajub, un litige perdu retire le montant contesté de votre solde, plafonné à ce qui n'est pas déjà sorti par un remboursement sur le même paiement, pour que l'argent ne puisse pas être pris deux fois. Sur un paiement encaissé par votre propre compte chez un prestataire, Wajub ne détient pas l'argent, et le prestataire règle la rétrofacturation directement avec vous.

Des frais de litige forfaitaires s'ajoutent, 15 000 XAF par défaut dans la devise du litige, quand la perte vient de l'API, avec accept ou close, ou d'une rétrofacturation du prestataire. Accepter depuis le Dashboard ne les facture pas. Perdre un litige de 25 000 XAF par l'API coûte donc 40 000 XAF, et non 25 000. Les débits ont lieu au changement de statut lui-même, pas lors d'un appel que vous feriez ensuite.

Un litige ne change pas le statut du paiement d'origine. Le remboursement créé quand vous acceptez s'y lit comme n'importe quel autre, à partir de la version 2026-10-11 de l'API. Quand vous acceptez, le remboursement que Wajub crée pour le payeur est un remboursement ordinaire, avec ses propres événements refund.*, à ceci près qu'il ne retire pas le montant contesté une seconde fois : la perte l'a retiré une fois, quel que soit l'ordre d'enregistrement, et le remboursement l'envoie au payeur. Si le payeur a payé les frais Wajub en plus du prix (bearer: customer), ces frais vous sont débités aussi, puisque le payeur récupère tout ce qu'il a payé. Le mouvement d'argent apparaît sur votre solde, et c'est là que vous le rapprochez.

La perte alimente aussi le score de risque : un litige perdu augmente le risque évalué du payeur concerné, et Shield examine donc ses futurs paiements avec plus de méfiance.

Webhooks

Sept événements, et ceux qui méritent une action sont les issues, plus le rappel.

dispute.deadline_approaching est envoyé en live comme en sandbox, pour chaque litige qui a une due_date : litiges Pocket et rétrofacturations à l'identique. L'écriture de metadata.reminded_at sur le litige envoie aussi un dispute.updated à côté.

Dédupliquez sur X-Wajub-Delivery-Id, comme partout ailleurs. L'enregistrement et la vérification de signature sont décrits dans Webhooks.

Dans le Dashboard

Disputes les liste avec leur statut et le paiement concerné. Ouvrir un litige vous donne la description du payeur, le fil de messages, et les trois mêmes actions que l'API, plus une qu'elle n'expose pas : vous pouvez marquer ici un litige comme gagné quand Wajub a tranché en votre faveur.

La section exige la permission manage_disputes, distincte de manage_payments, pour qu'un coéquipier puisse gérer les commandes sans pouvoir concéder un litige à votre place.

Moins de litiges coûte moins cher que d'en gagner

Un litige vous coûte du temps quelle qu'en soit l'issue, et le travail le plus rentable se fait donc avant qu'il n'existe.

Remboursez de bon gré quand un client se plaint et que vous n'avez pas d'argument : un remboursement que vous choisissez vous coûte le montant, un litige perdu vous coûte le montant plus les frais de litige forfaitaires. Gardez vos preuves de livraison là où vous pouvez les joindre en un clic. Et laissez Shield refuser les paiements les plus susceptibles de se retourner contre vous, puisqu'un paiement refusé d'emblée ne peut pas du tout être contesté.