Testing Disputes

The JustiFi dispute system provides a comprehensive test environment that simulates the complete dispute lifecycle. This allows you to test your dispute handling workflows without affecting live data or moving real money.

Creating Test Disputes

To create a dispute call the create payment API and pass the dispute_test_spec parameter in the metadata property as outlined below. This will create a successful payment with an associated dispute.

{
  "metadata": {
    "dispute_test_spec": {
      "expected_result": "won",
      "reason": "fraudulent",
      "forfeit": false,
      "due_date": "2024-02-15",
      "event_publish_delay_in_seconds": 60
    }
  }
}

Test Workflow

1. Payment Creation: A payment with dispute_test_spec key inside metadata
2. Dispute Creation: System creates dispute with needs_response status
3. Response Building: Test evidence upload and response field updates
4. Resolution: Dispute resolves based on your expected_result configuration after event_publish_delay_in_seconds seconds
5. Webhook Events: Receive all lifecycle events for testing

Configuration Options

The following options are available to customize the dispute details and outcome.

Expected Results

• won - Dispute resolves in the merchant`s favor, funds returned to the merchant
• lost - Dispute resolves against the merchant, no funds are moved

Dispute Reasons

• fraudulent - Customer claims they didn't authorize the payment
• unrecognized - Customer doesn't recognize the transaction
• duplicate - Customer claims they were charged multiple times
• subscription_canceled - Customer claims they canceled their subscription
• product_unacceptable - Customer claims the product was defective
• product_not_received - Customer claims they never received the product
• processing_error - Customer claims there was a processing error
• credit_not_processed - Customer claims a refund wasn't processed
• general - General dispute reason
• debit_not_authorized - The debit was not authorized
• incorrect_account - The account is not correct

Timing Configuration

• due_date - Response deadline in YYYY-MM-DD format (typically 7-10 business days)
• event_publish_delay_in_seconds - Delay before dispute creation event (default: 60)

Testing Evidence Upload

To upload evidence for the dispute you can either use the Dispute Management web component or the create dispute evidence API and submit Dispute Response API

Supported File Types

File Type	Extensions	MIME Types
Images	.jpg, .jpeg, .png	image/jpeg, image/png
Documents	.pdf	application/pdf
Archives	.zip	application/zip, application/x-zip-compressed

Evidence Categories

Choose the appropriate category for each piece of evidence:

• receipt - Purchase receipts and invoices
• shipping_documentation - Tracking numbers, delivery confirmations
• customer_communication - Email exchanges, chat logs
• customer_signature - Signed delivery receipts
• refund_policy - Terms of service, refund policies
• cancellation_policy - Cancellation terms and conditions
• service_documentation - Proof of service delivery
• duplicate_charge_documentation - Evidence for duplicate charge disputes
• activity_log - System activity logs
• uncategorized_file - Other supporting documents

Testing Response Scenarios

Comprehensive Response Example

{
  "customer_name": "John Doe",
  "customer_email_address": "john@example.com",
  "customer_billing_address": "123 Main St, Anytown, ST 12345",
  "customer_purchase_ip_address": "192.168.1.1",
  "product_description": "Premium software subscription with advanced features",
  "service_date": "2024-01-15",
  "shipping_address": "123 Main St, Anytown, ST 12345",
  "shipping_carrier": "FedEx",
  "shipping_date": "2024-01-16",
  "shipping_tracking_number": "1234567890",
  "refund_policy_disclosure": "Customer agreed to no-refund policy during checkout",
  "additional_statement": "Customer received and actively used the service as confirmed by login logs and feature usage analytics."
}

Testing Forfeiture

If you choose not to contest the dispute either use the submit dispute response API with the following body:

{
  "forfeit": true
}

Or instead forfeit the dispute via Dispute Management web component.

This immediately transitions the dispute to lost status.

Status Flow Testing

Test each status transition:

1. needs_response - Initial status after dispute creation
2. under_review - Automatic after response submission
3. won or lost - Based on expected_result configuration

Webhook Testing

Test disputes generate all standard webhook events:

• payment.dispute.created - Lets you know anytime a customer opens a payment dispute
• payment.dispute.closed - Lets you know anytime a payment dispute is closed
• payment.dispute.funds_returned - Lets you know anytime a payment dispute won and funds are returned
• payment.dispute_evidence.created - Lets you know anytime a dispute evidence is created
• payment.dispute_evidence.uploaded - Lets you know anytime a dispute evidence is uploaded
• payment.dispute.forfeited - Lets you know anytime a dispute response is forfeited
• payment.dispute.submitted - Lets you know anytime a dispute response is submitted

Configure webhook endpoints in your test account to receive and process these events.