Disputes
A dispute arises when a customer questions a charge with their card issuer. Upon such an occurrence, you are afforded the opportunity to provide evidence demonstrating the validity of the charge.
The Dispute object
Attributes
Unique identifier for the object.
Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).
ID of the charge that's refunded.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
Evidence provided to respond to a dispute. Updating any field in the hash submits all fields in the hash for review.
Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity.
The billing address provided by the customer.
Your subscription cancellation policy, as shown to the customer.
An explanation of how and when the customer was shown your refund policy prior to purchase.
A justification for why the customer's subscription was not canceled.
The email address of the customer.
The name of the customer.
The IP address that the customer used when making the purchase.
An explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate.
The Frame ID for the prior charge which appears to be a duplicate of the disputed charge.
A description of the product or service that was sold.
Documentation demonstrating that the customer was shown your refund policy prior to purchase.
The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.
Any additional evidence or statements.
ID of the ChargeIntent that's refunded.
Reason given by cardholder for dispute. Possible values are bank_cannot_process, check_returned, credit_not_processed, customer_initiated, debit_not_authorized, duplicate, fraudulent, general, incorrect_account_details, insufficient_funds, product_not_received, product_unacceptable, subscription_canceled, or unrecognized.
Current status of dispute. Possible values are warning_needs_response, warning_under_review, warning_closed, needs_response, under_review, won, or lost.
String representing the object's type. Objects of the same type share the same value.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
Time at which the object was created. Measured in seconds since the Unix epoch.
Time at which the object was last updated. Measured in seconds since the Unix epoch.
Example response
Update a dispute
Upon receiving a dispute, initiating contact with your customer is advised as the primary step. Should direct communication prove ineffective, you can opt to submit evidence through your dashboard. Alternatively, you have the option to programmatically submit evidence via the API.
Different types of disputes may require specific evidence fields to increase the likelihood of a favorable resolution.
Parameters
Evidence provided to respond to a dispute. Updating any field in the hash submits all fields in the hash for review.
Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity.
The billing address provided by the customer.
Your subscription cancellation policy, as shown to the customer.
An explanation of how and when the customer was shown your refund policy prior to purchase.
A justification for why the customer's subscription was not canceled.
The email address of the customer.
The name of the customer.
The IP address that the customer used when making the purchase.
An explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate.
The Frame ID for the prior charge which appears to be a duplicate of the disputed charge.
A description of the product or service that was sold.
Documentation demonstrating that the customer was shown your refund policy prior to purchase.
The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.
Any additional evidence or statements.
Whether to immediately submit evidence to the bank. If false, evidence is staged on the dispute. Staged evidence is visible in the API and Dashboard, and can be submitted to the bank by making another request with this attribute set to true (the default).
Returns
Returns the dispute object.
example response
Retrieve a dispute
Retrieves the dispute with the given ID.
Parameters
No parameters.
Returns
Returns a dispute if a valid dispute ID was provided. Returns an error otherwise.
Example response
List all disputes
Returns a list of your disputes.
Parameters
Only return disputes associated to the charge specified by this charge ID.
Only return disputes associated to the ChargeIntent specified by this ChargeIntent ID.
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.
The page offset at which you'd like to resume fetching data.
Returns
A dictionary with a data property that contains an array of up to per_page disputes. Each entry in the array is a separate Dispute object. If no other disputes are available, the resulting array is empty.
Example response
Close a dispute
Closing a dispute for a charge signifies the absence of evidence to submit, effectively conceding the dispute and acknowledging it as lost.
The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.
Parameters
No parameters.
Returns
Returns the dispute object.
Example response