## How it works

A dispute records a customer's challenge to a payment. Track its stage, current status and challenge_required_by deadline independently from the payment's status.

## Implementation

Retrieve the case, decide whether to accept or challenge it, and prepare the evidence that the processor permits. File IDs and structured text fields can describe delivery, customer communication, service access, cancellation policies and recurring consent. Submit before the deadline and monitor dispute events for the result. PayPal cases have a separate case workflow and may require processor-specific actions.

## Dispute states

| Stage | Meaning |
| --- | --- |
| `pre_dispute` | Inquiry before a chargeback. |
| `dispute` | Formal chargeback. |
| `pre_arbitration` | Second round after the first decision. |
| `arbitration` | The card network decides. |
| `dispute_reversal` | Outcome reversed. |

## Challenge with evidence

| Kind | Fields |
| --- | --- |
| File (`file_id`) | `receipt`, `customer_communication`, `customer_signature`, `shipping_documentation`, `service_documentation`, `cancellation_policy`, `refund_policy`, `invoice_showing_distinct_transactions`, `recurring_transaction_agreement`, `uncategorized_file` |
| Text | `product_description`, `customer_email_address`, `customer_name`, `customer_purchase_ip`, `billing_address`, `shipping_address`, `shipping_carrier`, `shipping_date`, `shipping_tracking_number`, `service_date`, `access_activity_log`, `cancellation_policy_disclosure`, `cancellation_rebuttal`, `refund_policy_disclosure`, `refund_refusal_explanation`, `duplicate_charge_id`, `duplicate_charge_explanation`, `uncategorized_text` |

## Challenge with evidence

| Task | Request |
| --- | --- |
| Attach a file | `PUT /disputes/evidence` (multipart `file`, `dispute_id`, `evidence_type`) |
| List attached | `GET /disputes/evidence/{dispute_id}` |
| Remove one | `DELETE /disputes/evidence` with `{"dispute_id": "dp_xxxxx", "evidence_type": "receipt"}` |

## HTTP example

```text
dispute_opened -[evidence submitted]-> dispute_challenged -> dispute_won {success}
dispute_challenged -> dispute_lost {danger}
dispute_opened -[you accept]-> dispute_accepted
dispute_opened -[deadline passes]-> dispute_expired
dispute_opened -[withdrawn]-> dispute_cancelled
```

## Related guides

- [Webhook events](/docs/payment-api/webhooks/)
- [API reference](/docs/payment-api/reference/)

## Request examples

```bash
curl https://api.spicepay.net/disputes/dp_xxxxx \
  -H 'api-key: YOUR_API_KEY'
```

```bash
curl 'https://api.spicepay.net/disputes/list?limit=20' \
  -H 'api-key: YOUR_API_KEY'
```

```bash
curl -X POST https://api.spicepay.net/disputes/accept/dp_xxxxx \
  -H 'api-key: YOUR_API_KEY'
```

```bash
   curl -X POST https://api.spicepay.net/files \
     -H 'api-key: YOUR_API_KEY' \
     -F purpose=dispute_evidence \
     -F dispute_id=dp_xxxxx \
     -F file=@receipt.pdf
   ```

```bash
   curl -X POST https://api.spicepay.net/disputes/evidence \
     -H 'api-key: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
       "dispute_id": "dp_xxxxx",
       "receipt": "file_xxxxx",
       "customer_email_address": "ada@example.com",
       "shipping_tracking_number": "1Z999AA10123456784",
       "uncategorized_text": "The buyer confirmed delivery by email on 2026-07-01."
     }'
   ```