Dispute Lifecycle

Dispute Creation

A dispute (also known as chargeback) is created when a cardholder contacts their card issuer to question a payment. The card issuer opens a chargeback and returns the questioned funds to the cardholder. JustiFi is notified of the chargeback, creates a dispute associated with the payment and pulls the payment funds (and a dispute fee) back from the merchant. As soon as JustiFi has created the dispute:

1. Notification: You receive a payment.dispute.created webhook event
2. Timeline: You have 7-10 business days to respond (varies by card network)

Response Phase

Building Your Response

During the response phase, you can:

• Upload Evidence: Add supporting documents via the create dispute evidence API or via Dispute Management web component
• Update Response Fields: Fill in detailed information about the transaction

Response Fields

Provide comprehensive information across these categories:

Customer Information

• customer_name - Full customer name
• customer_email_address - Customer email
• customer_billing_address - Billing address
• customer_purchase_ip_address - IP address at purchase time

Transaction Details

• product_description - Detailed product/service description
• service_date - Date service was provided
• duplicate_charge_original_payment_id - Reference for duplicate charges
• duplicate_charge_explanation - Explanation for duplicate charges

Shipping Information

• shipping_address - Delivery address
• shipping_carrier - Shipping company
• shipping_date - Ship date
• shipping_tracking_number - Tracking number

Policy Information

• refund_policy_disclosure - Refund policy terms
• cancellation_policy_disclosure - Cancellation policy terms
• refund_refusal_explanation - Why refund was refused
• cancellation_rebuttal - Response to cancellation claims

Additional Context

• additional_statement - Free-form additional information

Evidence Management

Evidence Categories

Category	Best Used For
receipt	Purchase confirmations, invoices
shipping_documentation	Delivery proof, tracking info
customer_communication	Email exchanges, support tickets
customer_signature	Signed delivery receipts
refund_policy	Terms of service, policies
cancellation_policy	Cancellation terms
service_documentation	Proof of service delivery
duplicate_charge_documentation	Duplicate charge evidence
activity_log	System logs, usage data
uncategorized_file	Other supporting documents

File Requirements

• Supported formats: PDF, JPG, JPEG, PNG, ZIP
• Validation: File extension must match MIME type

Submission and Review

Forfeiture Option

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 and sends a payment.dispute.forfeited event, followed by a payment.dispute.closed event.

A dispute is only forfeited when you explicitly request it as shown above.

Resolution Phase

Possible Outcomes

Won (won status)

• Appeal window: When the card network rules in your merchant's favor, the dispute is under_review for 60 days while the cardholder's issuer can appeal. funds_held_until on the dispute shows when that window ends.
• Funds Returned: When the window closes with no appeal, or your merchant wins the appeal, the dispute status becomes won and the disputed amount is returned to your merchant's account.
• Notification: payment.dispute.funds_returned and payment.dispute.closed webhook events, sent when the funds are returned. See Issuer Appeals

Lost (lost status)

• Funds Retained: No funds are moved.
• Notification: payment.dispute.closed webhook event

Dispute Reversals

Card networks can reverse lost disputes:

1. Reversal Trigger: New evidence or network decision
2. Dispute updated: Status of dispute is updated to won
3. Fund Return: Previously lost funds are returned
4. Notification: payment.dispute.closed webhook event

Issuer Appeals

The cardholder's issuer can appeal a dispute the card network ruled in your merchant's favor. JustiFi tracks the appeal on the same dispute, holds the disputed amount for the 60 day appeal window and returns it when the window closes without an appeal or your merchant wins the appeal. See Issuer Appeals.

Status Transitions

needs_response → under_review → lost
       ↓              ↓
lost (forfeited)   ruled for the merchant: stays under_review for the 60 day appeal window
                      ├─ no appeal, or merchant wins the appeal → won (funds returned)
                      └─ merchant loses the appeal → lost

lost → won (loss reversed by the card network)

Status Descriptions

• needs_response - Initial status, response deadline active
• under_review - Response submitted and the card network is reviewing, or the card network ruled for the merchant and the 60 day appeal window is open (funds_held_until is set)
• won - Dispute resolved in merchant's favor: the appeal window closed without an appeal, or the merchant won the appeal. Funds returned to the merchant
• lost - Dispute resolved against the merchant, forfeited, or lost on an issuer appeal

Webhook Events

Monitor these events for real-time updates. Their payloads are described in the dispute event and dispute evidence event references:

• 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, including when a won dispute is lost on an issuer appeal
• payment.dispute.funds_returned - Lets you know anytime a payment dispute is won and funds are returned, which is when the appeal window closes without an appeal or your merchant wins the appeal
• 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 (the dispute moves to lost and a payment.dispute.closed event follows)
• payment.dispute.submitted - Lets you know anytime a dispute response is submitted (the dispute moves to under_review)
• payment.dispute.pre_arbitration_received - Lets you know anytime the cardholder's issuer appeals a dispute your merchant won (pre_arbitration becomes true). See Issuer Appeals