Disputes

Created by Kalin Ivanov, Modified on Tue, 23 Jun at 8:41 AM by Kalin Ivanov

ℹ️ Note

The Disputes API is in active development and not yet exposed on the public API. This page documents the shape so you can plan an integration. The contract below will not change in incompatible ways at launch.

A dispute represents a chargeback or related challenge raised against one of your payments. SwissPay normalises events from every connected processor into a single provider-neutral resource, so your handling code does not need to branch on processor.

The Dispute object

{
  "id": "dsp_01HABCXYZ...",
  "payment": "pay_01HABCXYZ...",
  "customer": "cus_01HCUSXYZ...",
  "amount": 2999,
  "currency": "CHF",
  "state": "chargeback",
  "status": "action_required",
  "reason": "fraud_card_absent",
  "respond_by": "2026-06-04T23:59:59Z",
  "raised_at": "2026-05-20T12:00:00Z",
  "payment_method": {
    "type": "card",
    "brand": "visa",
    "last4": "1111"
  },
  "arn": "12345600000000000000001",
  "metadata": {}
}

Field	Type	Notes
`id`	string	Stable, prefixed with `dsp_`.
`payment`	string	The `pay_...` ID under dispute.
`customer`	string \| null	The `cus_...` ID of the customer attached to the disputed payment, when one was attached.
`amount` / `currency`	int / string	The disputed amount in minor units. May be less than the original payment for partial disputes.
`state`	string	The dispute lifecycle stage â see below.
`status`	string	The action required (or completed).
`reason`	string	Card-network reason code translated to a stable enum.
`respond_by`	string	ISO 8601 deadline by which a defence must be submitted.
`arn`	string \| null	Acquirer Reference Number, when the processor returned one.
`payment_method`	object	Same shape as on `Payment` â brand + BIN + last4 only.

State and status

state traces the dispute through the network's lifecycle:

State	Meaning
`information_request`	The issuer has asked for documentation â not yet a chargeback.
`chargeback`	A formal chargeback has been filed.
`pre_arbitration`	The issuer has rejected the first defence and re-raised the dispute.
`scheme_arbitration`	The card network is adjudicating.
`second_chargeback`	A new chargeback filed after a previous one was reversed.

status reflects what you need to do:

Status	Meaning
`new`	We have received the dispute; nothing required from you yet.
`action_required`	You must accept or defend before `respond_by`.
`challenged`	You submitted a defence; awaiting outcome.
`recovered`	A previously-lost dispute has been reversed in your favour.
`accepted`	You chose to accept (or did not respond).
`lost`	The dispute was decided against you.
`won`	The dispute was decided in your favour.

Planned endpoints

When the API ships, you will be able to:

GET /api/v1/disputes â list disputes for your merchant account, with filters by state, status, payment, and time range.
GET /api/v1/disputes/{id} â retrieve a single dispute.
POST /api/v1/disputes/{id}/accept â accept the loss and stop the challenge.
POST /api/v1/disputes/{id}/defend â submit evidence to challenge.

The exact submission schema (and the evidence types each card scheme accepts) will be documented when the endpoints go live. Until then, dispute notifications will arrive via email and the dashboard.