Disputes API

The Disputes API allows you to view and respond to payment disputes (chargebacks).

The Dispute Object

{
  "id": "dp_abc123def456",
  "object": "dispute",
  "amount": 50,
  "currency": "GHS",
  "status": "needs_response",
  "reason": "fraudulent",
  "payment": "pay_xyz789",
  "evidence": {
    "customer_name": null,
    "customer_email_address": null,
    "product_description": null,
    "uncategorized_text": null
  },
  "evidence_due_by": "2024-02-15T00:00:00Z",
  "metadata": {},
  "created_at": "2024-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"dispute"`
`amount`	number	Disputed amount in GHS
`currency`	string	Currency code
`status`	string	Current dispute status
`reason`	string	Reason for the dispute
`payment`	string	Payment ID
`evidence`	object	Evidence submitted
`evidence_due_by`	string	Deadline for evidence submission
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Dispute Statuses

Status	Description
`warning_needs_response`	Early warning, response recommended
`warning_under_review`	Early warning, under review
`warning_closed`	Early warning closed
`needs_response`	Dispute requires your response
`under_review`	Evidence submitted, under review
`charge_refunded`	Charge was refunded
`won`	Dispute was decided in your favor
`lost`	Dispute was decided against you

List Disputes

GET /v1/disputes

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination
`payment`	string	Filter by payment ID
`status`	string	Filter by status

Retrieve a Dispute

GET /v1/disputes/:id

Submit Evidence

Updates a dispute with evidence. Set submit: true to submit the evidence for review.

POST /v1/disputes/:id

Request Body

Parameter	Type	Required	Description
`evidence`	object	No	Evidence fields (see below)
`metadata`	object	No	Custom metadata
`submit`	boolean	No	Submit evidence for review

Evidence Fields

Field	Type	Description
`access_activity_log`	string	Activity log showing customer access
`billing_address`	string	Customer billing address
`cancellation_policy`	string	Your cancellation policy
`cancellation_policy_disclosure`	string	How the policy was disclosed
`cancellation_rebuttal`	string	Rebuttal to cancellation claim
`customer_communication`	string	Communication with customer
`customer_email_address`	string	Customer email
`customer_name`	string	Customer name
`customer_purchase_ip`	string	Customer's IP at purchase
`customer_signature`	string	Customer signature
`duplicate_charge_documentation`	string	Documentation for duplicate charge
`duplicate_charge_explanation`	string	Explanation for duplicate charge
`duplicate_charge_id`	string	Original charge ID
`product_description`	string	Description of product/service
`receipt`	string	Receipt or proof of delivery
`refund_policy`	string	Your refund policy
`refund_policy_disclosure`	string	How the refund policy was disclosed
`refund_refusal_explanation`	string	Why refund was refused
`service_date`	string	Date service was provided
`service_documentation`	string	Documentation of service
`shipping_address`	string	Shipping address
`shipping_carrier`	string	Shipping carrier
`shipping_date`	string	Date shipped
`shipping_documentation`	string	Shipping documentation
`shipping_tracking_number`	string	Tracking number
`uncategorized_file`	string	Additional file evidence
`uncategorized_text`	string	Additional text evidence

curl -X POST https://api.shikacreators.com/v1/disputes/dp_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_name": "John Doe",
      "customer_email_address": "john@example.com",
      "product_description": "Monthly subscription to Pro plan",
      "uncategorized_text": "Customer accessed the service 15 times after the disputed charge."
    },
    "submit": true
  }'

const dispute = await shikacreators.disputes.update('dp_abc123def456', {
  evidence: {
    customer_name: 'John Doe',
    customer_email_address: 'john@example.com',
    product_description: 'Monthly subscription to Pro plan',
    uncategorized_text: 'Customer accessed the service 15 times after the disputed charge.'
  },
  submit: true
})

Once evidence is submitted (submit: true), it cannot be modified. Make sure all evidence is complete before submitting.

Close a Dispute

Closes a dispute, accepting the chargeback. The dispute status will be set to lost.

POST /v1/disputes/:id/close

curl -X POST https://api.shikacreators.com/v1/disputes/dp_abc123def456/close \
  -H "Authorization: Bearer sk_test_..."

const dispute = await shikacreators.disputes.close('dp_abc123def456')

Closing a dispute means you accept the chargeback. The disputed amount will be deducted from your balance.

Disputes

On this page