Disputes and chargebacks

Maxana exposes disputes and chargebacks raised against the authenticated merchant. The list is provider-synchronized; the detail response adds the current available_actions, sanitized provider payload, and merchant-visible notes.

Request fields are strict: an unrecognized property in an action body, or within an evidence entry, returns 422 Unprocessable Entity. Send only the documented fields and field names.

Response workflow

1. Ingest dispute.created, dispute.updated, and deadline events through a replay-safe webhook handler.
2. Fetch the dispute detail using its Maxana identifier.
3. Inspect available_actions before responding. Valid actions depend on the dispute’s current status and lifecycle stage.
4. Submit evidence, supporting information, a message, an offer, escalation, acceptance, return acknowledgement, or appeal only when the detail permits it.
5. Re-fetch after the action and retain your own evidence and audit trail.

Deadlines are operational deadlines. Alert before them, retain the exact evidence submitted, and do not assume that a browser confirmation or one webhook is the final provider decision.

Current limits

The API cannot make an action available when the provider’s current dispute stage excludes it, and submitting an action does not guarantee the provider’s final decision. Re-read the dispute after each action and treat its current available_actions as authoritative.