Docs/Payment-API
SPICEPAY DEVELOPER DOCS

Disputes

A dispute records a customer's challenge to a payment.

◷ 2 min readEnglish · API referenceMarkdown öffnen ↗

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

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 [email protected]
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": "[email protected]",
       "shipping_tracking_number": "1Z999AA10123456784",
       "uncategorized_text": "The buyer confirmed delivery by email on 2026-07-01."
     }'

Fragen zu deiner Integration? SpicePay kontaktieren ↗