Disputes#

A Dispute occurs when a tenant questions a charge with their bank. CasaPay notifies you and provides tools to submit evidence.

The Dispute object#

Attribute	Type	Description
`id`	string	Unique identifier with `dp_` prefix
`object`	string	Always `"dispute"`
`charge`	string	Disputed Charge ID
`payment_intent`	string	Associated PaymentIntent ID
`amount`	integer	Disputed amount
`currency`	string	ISO 4217 currency code
`status`	enum	`warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`
`reason`	enum	`duplicate`, `fraudulent`, `general`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, `unrecognized`
`evidence`	object	Evidence submitted
`evidence_due_by`	timestamp	Deadline to submit evidence
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the object was created

{
  "id": "dp_xyz789",
  "object": "dispute",
  "charge": "ch_abc123",
  "payment_intent": "pi_1a2b3c4d",
  "amount": 120000,
  "currency": "eur",
  "status": "needs_response",
  "reason": "unrecognized",
  "evidence": {},
  "evidence_due_by": 1707350400,
  "created": 1706140800
}

Retrieve a Dispute#

GET /v1/disputes/:id

curl https://api.casapay.com/v1/disputes/dp_xyz789 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Update a Dispute (Submit Evidence)#

POST /v1/disputes/:id

Parameter	Type	Description
`evidence`	object	Evidence to submit
`evidence.customer_name`	string	Customer's name
`evidence.customer_email`	string	Customer's email
`evidence.billing_address`	string	Billing address
`evidence.receipt`	string	File ID of receipt
`evidence.service_documentation`	string	File ID of lease/contract
`submit`	boolean	Whether to submit evidence (cannot be undone)

curl https://api.casapay.com/v1/disputes/dp_xyz789 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_name": "Jane Doe",
      "customer_email": "jane@example.com",
      "service_documentation": "file_lease_001"
    },
    "submit": true
  }'

Close a Dispute#

Accept the dispute and refund the tenant.

POST /v1/disputes/:id/close

curl -X POST https://api.casapay.com/v1/disputes/dp_xyz789/close \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

List Disputes#

GET /v1/disputes

Parameter	Type	Description
`charge`	string	Filter by charge
`payment_intent`	string	Filter by PaymentIntent
`status`	string	Filter by status

curl "https://api.casapay.com/v1/disputes?status=needs_response" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"