Disputes

Buyers or sellers can open disputes on active or awaiting_confirmation escrows. Disputes lock the escrow until resolved and include a message thread for communication between parties. Merchants or admins can resolve disputes.

Dispute reasons

Reason	Description
`item_not_received`	Buyer did not receive the item
`item_not_as_described`	Item received but does not match description
`service_not_delivered`	Service was not performed
`other`	Other reason (requires description)

Resolution options

Resolution	Effect
`release_to_seller`	Funds released to seller, escrow completed
`refund_buyer`	Full refund to buyer, escrow refunded
`partial_refund`	Partial amount refunded to buyer, remainder to seller

Integrating disputes (API key)

The integration model is deliberately simple: your system opens the dispute; the conversation happens on Kashia's hosted pages. Opening a dispute returns a buyer_dispute_url and a seller_dispute_url— each link drops that person straight into the escrow's dispute chat, where the buyer, the seller, you (the merchant, from your dashboard), and Kashia's admin or assigned dispute officer all converge on one thread. There are no API endpoints for reading or posting messages — that is by design.

The user_idis the party opening the dispute — the escrow's buyer or seller. Anyone else is refused with 403.
Evidence files can be attached at opening by sending multipart/form-data instead of JSON, with files under attachments — they appear in the chat as its first message, credited to the opening party. Images and PDFs are accepted; a refused file fails the whole request and creates nothing.
Links expire — mint a fresh one for either party any time with POST /external/disputes/:disputeId/access-link.
One dispute per escrow: opening a second one returns 400 while a dispute already exists.

POST/api/v1/external/escrows/:escrowId/disputes

Open a dispute on an escrow, optionally with evidence files. Returns hosted dispute links for both parties.

Request example (JSON, no files)

bash

curl -X POST https://vault-api.kashiahq.com/api/v1/external/escrows/cb3dc305-2061-4d1b-9062-aec4c33fd849/disputes \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "f7b16e1f-6761-48e7-9ceb-5d0981e8e650",
    "reason": "item_not_received",
    "description": "Nothing arrived after two weeks."
  }'

Request example (multipart, with evidence)

bash

curl -X POST https://vault-api.kashiahq.com/api/v1/external/escrows/cb3dc305-2061-4d1b-9062-aec4c33fd849/disputes \
  -H "X-API-Key: your_api_key" \
  -F "user_id=f7b16e1f-6761-48e7-9ceb-5d0981e8e650" \
  -F "reason=item_not_received" \
  -F "description=Nothing arrived after two weeks." \
  -F "attachments=@photo1.png" \
  -F "attachments=@receipt.pdf"

Response

json

{
  "success": true,
  "data": {
    "dispute_id": "…",
    "dispute_reference": "DSP-397ef1e3",
    "status": "open",
    "buyer_dispute_url": "https://vault.kashiahq.com/action/aee07d…  (64-char token)",
    "seller_dispute_url": "https://vault.kashiahq.com/action/aee07d…  (64-char token)",
    "created_at": "2025-01-15T10:30:00Z",
    "evidence_message": {
      "sender_type": "buyer",
      "message": "Evidence attached with this dispute.",
      "attachments": [
        { "id": "…", "filename": "photo1.png", "mime_type": "image/png", "file_size": 20481 },
        { "id": "…", "filename": "receipt.pdf", "mime_type": "application/pdf", "file_size": 88213 }
      ]
    }
  }
}

evidence_message is present only when files were sent (it also carries id, dispute_id, sender_id, and created_at). Send (or redirect) each party to their link.

Parameters
Parameter	Type	Required	Description
`user_id`	string (UUID)	Yes	The buyer or seller opening the dispute.
`reason`	string	Yes	One of "item_not_received", "item_not_as_described", "service_not_delivered", "other".
`description`	string	Yes	What happened, in the opener's words — shown at the top of the dispute page.
`attachments`	file[]	No	Multipart only — evidence files (images, PDF). Become the chat's first message.

POST/api/v1/external/disputes/:disputeId/access-link

Mint a fresh hosted dispute link for the buyer or seller (links expire).

Parameters
Parameter	Type	Required	Description
`user_id`	string (UUID)	Yes	The buyer or seller the link is for.

Dashboard endpoints (session auth)

POST/api/v1/escrows/:id/disputes

Open a dispute. Buyer or seller.

Request example

bash

{
  "reason": "item_not_received",
  "description": "I paid 3 days ago but have not received any shipping notification."
}

GET/api/v1/disputes/:id

Get dispute details including message thread.

GET/api/v1/merchant/disputes

List disputes for the authenticated merchant.

POST/api/v1/disputes/:id/messages

Add a message to the dispute thread.

Request example

bash

{
  "message": "Here is the tracking number: NG12345678"
}

POST/api/v1/disputes/:id/resolve

Resolve a dispute. Merchant or admin.

Request example

bash

{
  "resolution": "release_to_seller",
  "resolution_note": "Seller provided valid proof of delivery."
}

// partial_refund additionally REQUIRES resolution_amount (kobo, 1..amount):
{
  "resolution": "partial_refund",
  "resolution_amount": 4000000,
  "resolution_note": "Item arrived damaged; 40% refunded."
}

POST/api/v1/disputes/:id/escalate

Escalate dispute to Kashia admin. Buyer or seller.