Litige ( dispute )

Rôle

Le dossier n'est pas limité à une facture ni à un chargeback PSP. Il peut couvrir une ou plusieurs factures, des commandes, ou des lignes précisément contextualisées. Il conserve l'état métier stable du litige, indépendamment de la manière dont le processus le traite.

Structure

GET /v1/disputes/dis_4a7b

{
"id": "dis_4a7b",
"object": "dispute",
"merchant_id": "mer_1a2b",
"buyer_id": "cmp_9c3d",
"buyer_contact_id": "ctc_5e6f",
"reference": "DSP-2026-0042",
"subjects": [
  {
    "type": "invoice",
    "invoice_id": "inv_7a8b",
    "amount": 12000,
    "reason": "incorrect_amount"
  }
],
"currency": "eur",
"amount_disputed": 12000,
"amount_accepted": null,
"status": "open",
"resolution_status": "pending",
"related_objects": [],
"process_definition_id": "prd_1b2c",
"process_instance_id": "pci_3d4e",
"process_status": "waiting",
"url": "https://…",
"opened_at": "2026-08-24T14:00:00.000Z",
"closed_at": null
}

Subjects

subjects contient uniquement les éléments effectivement contestés. Les types supportés sont invoice, order et line_item. Chaque subject porte son propre reason et peut porter un montant.

[
{
  "type": "invoice",
  "invoice_id": "inv_7a8b",
  "amount": 12000,
  "reason": "incorrect_amount"
},
{
  "type": "line_item",
  "line_item_id": "li_2f3a",
  "invoice_id": "inv_7a8b",
  "order_id": "ord_6c7d",
  "quantity": 2,
  "amount": 4000,
  "reason": "product_unacceptable"
}
]

Un line_item n'est jamais contesté sans contexte : il doit référencer au moins une invoice ou une order, et peut référencer les deux lorsque les relations sont cohérentes. Tous les subjects monétaires d'un même dossier utilisent la même devise.

Cycle de vie

status décrit le cycle de vie du dossier. resolution_status décrit séparément la conclusion commerciale.

Processus associé

La création d'un dispute sélectionne un processus compatible avec un input typé platform.dispute. Vous pouvez fournir explicitement process_definition_id ou utiliser le launcher système dispute configuré pour le marchand.

Les retries, replays ou forks correctifs transfèrent la propriété du dossier à la nouvelle instance. Seule l'instance courante peut ensuite modifier ou finaliser le litige avec les nodes dédiés.

Résolution

Le processus décide explicitement des actions à effectuer avant de finaliser le dossier : créer un avoir, initier un remboursement, annuler une commande, créer un retour ou toute autre action métier. Le node Finalize dispute ne crée aucun de ces objets automatiquement.

Les objets importants produits pendant le traitement peuvent être référencés dans related_objects avec un rôle métier, par exemple resolution_credit_note, resolution_refund ou resolution_return.

Impact sur les factures

Lorsqu'un litige open couvre une invoice ou une ligne contextualisée par cette invoice, la facture expose disputed = true. La projection reste vraie tant qu'au moins un dossier ouvert couvre encore la facture.

Le receivable expose séparément les balances contestées et non contestées. Le Payment Commitment ne porte aucune notion de montant contesté ou collectable.

API

POST /v1/disputes

{
"merchant_id": "mer_1a2b",
"buyer_id": "cmp_9c3d",
"reference": "DSP-2026-0042",
"subjects": [
  {
    "type": "invoice",
    "invoice_id": "inv_7a8b",
    "amount": 12000,
    "reason": "incorrect_amount"
  }
],
"amount_disputed": 12000
}

GET /v1/disputes
GET /v1/disputes/dis_4a7b
POST /v1/disputes/dis_4a7b
GET /v1/invoices/inv_7a8b/disputes

Tant que le dossier est open, l'endpoint de mise à jour peut modifier son périmètre, ses objets liés et ses références. La conclusion finale appartient au processus via les nodes Finalize dispute et Cancel dispute.

Événements