About UsStatus Page
Developer API
Start typing to search…

Dispute Management

The Disputes API provides the ability to retrieve information about disputes related to transactions in your merchant account. Additionally, you can submit supporting evidence to resolve disputes, helping to ensure fair outcomes and maintain merchant satisfaction.

Disputes are typically initiated by customers through their issuing bank. The API allows you to programmatically handle disputes, upload evidence, and monitor their resolution status.

Quick Links

List Disputes Retrieve all disputes associated with your merchant account. Submit Evidence Upload evidence to support your case for a dispute. Dispute Webhook Triggered when a new dispute is created.

Sandbox Testing

Triggering a Dispute

  1. To create a mock dispute in a sandbox account:
  2. Create a payment for $8888.88 using the Stax.js pay() method or the Charge a Payment Method API.
    Navigate to Stax Pay → Reports → Deposit Report.
  3. Click on Simulate Settlements.
  4. Verify the dispute appears via:
    1. List Disputes API.
    2. Stax Pay Sandbox Dashboard → Reports → Chargeback Manager.

Simulating Different Dispute Statuses

In sandbox accounts, disputes default to the PENDING status (unless they are of type INQUIRY). You can simulate different dispute statuses by passing the sandbox-only &status= query parameter when submitting evidence. Use one of the following enum values as the parameter:

  • PENDING
  • WON
  • LOST
  • EVIDENCE_UPLOADED
  • UPLOAD_FAILED

Example: Append ?status=WON to simulate a successful resolution.

Dispute Statuses

StatusDescription
INQUIRYThe issuer requests evidence to resolve the dispute before engaging in the chargeback process.
OPENThe dispute requires action from the merchant.
PENDINGA response is pending from either party, with no resolution yet.
ACCEPTEDThe dispute has been accepted by a user of either Stax Pay or Stax Connect, leading the dispute to expire.
PREARBITRATIONThe dispute has been reopened for pre-arbitration. Contact support if arbitration is required.
WONSufficient evidence has been provided, and the dispute was resolved in favor of the merchant.
LOSTInsufficient evidence was provided, resulting in a resolution favoring the customer.
EVIDENCE_UPLOADEDSupporting documents have been successfully uploaded.
UPLOAD_FAILEDAn attempt to upload documents failed.

Example Workflows

Retrieve All Disputes

  1. Call the List Disputes API to fetch all disputes.
  2. Filter the response by status to identify unresolved disputes.

Submit Evidence

  1. Collect necessary evidence (e.g., transaction receipts, signed agreements).
  2. Call the Submit Evidence API with the required files.
  3. Monitor the dispute status through the List Disputes API or webhook notifications.