When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit evidence to help us resolve the dispute in your favor. You can do this in your dashboard, but if you prefer, you can use the API to submit evidence programmatically.
Depending on your dispute type, different evidence fields will give you a better chance of winning your dispute. To figure out which evidence fields to provide, see our guide to dispute types.
Parameters
- evidenceobject
Evidence to upload, to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review. The combined character count of all fields is limited to 150,000.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to
metadata. - submitboolean
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 totrue(the default).
Returns
Returns the dispute object.
{ "id": "du_1MtJUT2eZvKYlo2CNaw2HvEv", "object": "dispute", "amount": 1000, "balance_transactions": [], "charge": "ch_1AZtxr2eZvKYlo2CJDX8whov", "created": 1680651737, "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy": null, "cancellation_policy_disclosure": null, "cancellation_rebuttal": null, "customer_communication": null, "customer_email_address": null, "customer_name": null, "customer_purchase_ip": null, "customer_signature": null, "duplicate_charge_documentation": null, "duplicate_charge_explanation": null, "duplicate_charge_id": null, "product_description": null, "receipt": null, "refund_policy": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": null, "service_documentation": null, "shipping_address": null, "shipping_carrier": null, "shipping_date": null, "shipping_documentation": null, "shipping_tracking_number": null, "uncategorized_file": null, "uncategorized_text": null }, "evidence_details": { "due_by": 1682294399, "has_evidence": false, "past_due": false, "submission_count": 0 }, "is_charge_refundable": true, "livemode": false, "metadata": { "order_id": "6735" }, "payment_intent": null, "reason": "general", "status": "warning_needs_response"}Retrieves the dispute with the given ID.
Parameters
No parameters.
Returns
Returns a dispute if a valid dispute ID was provided. Raises an error otherwise.
{ "id": "du_1MtJUT2eZvKYlo2CNaw2HvEv", "object": "dispute", "amount": 1000, "balance_transactions": [], "charge": "ch_1AZtxr2eZvKYlo2CJDX8whov", "created": 1680651737, "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy": null, "cancellation_policy_disclosure": null, "cancellation_rebuttal": null, "customer_communication": null, "customer_email_address": null, "customer_name": null, "customer_purchase_ip": null, "customer_signature": null, "duplicate_charge_documentation": null, "duplicate_charge_explanation": null, "duplicate_charge_id": null, "product_description": null, "receipt": null, "refund_policy": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": null, "service_documentation": null, "shipping_address": null, "shipping_carrier": null, "shipping_date": null, "shipping_documentation": null, "shipping_tracking_number": null, "uncategorized_file": null, "uncategorized_text": null }, "evidence_details": { "due_by": 1682294399, "has_evidence": false, "past_due": false, "submission_count": 0 }, "is_charge_refundable": true, "livemode": false, "metadata": {}, "payment_intent": null, "reason": "general", "status": "warning_needs_response"}Returns a list of your disputes.
Parameters
- chargestring
Only return disputes associated to the charge specified by this charge ID.
- payment_
intentstring Only return disputes associated to the PaymentIntent specified by this PaymentIntent ID.
More parameters
- createdobject
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
A dictionary with a data property that contains an array of up to limit disputes, starting after dispute starting_. Each entry in the array is a separate dispute object. If no more disputes are available, the resulting array will be empty.
{ "object": "list", "url": "/v1/disputes", "has_more": false, "data": [ { "id": "du_1MtJUT2eZvKYlo2CNaw2HvEv", "object": "dispute", "amount": 1000, "balance_transactions": [], "charge": "ch_1AZtxr2eZvKYlo2CJDX8whov", "created": 1680651737, "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy": null, "cancellation_policy_disclosure": null, "cancellation_rebuttal": null, "customer_communication": null, "customer_email_address": null, "customer_name": null, "customer_purchase_ip": null, "customer_signature": null, "duplicate_charge_documentation": null, "duplicate_charge_explanation": null, "duplicate_charge_id": null, "product_description": null, "receipt": null, "refund_policy": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": null, "service_documentation": null, "shipping_address": null, "shipping_carrier": null, "shipping_date": null, "shipping_documentation": null, "shipping_tracking_number": null, "uncategorized_file": null, "uncategorized_text": null }, "evidence_details": { "due_by": 1682294399, "has_evidence": false, "past_due": false, "submission_count": 0 }, "is_charge_refundable": true, "livemode": false, "metadata": {}, "payment_intent": null, "reason": "general", "status": "warning_needs_response" } ]}Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.
The status of the dispute will change from needs_ to lost. Closing a dispute is irreversible.
Parameters
No parameters.
Returns
Returns the dispute object.
{ "id": "du_1MtJUT2eZvKYlo2CNaw2HvEv", "object": "dispute", "amount": 1000, "balance_transactions": [], "charge": "ch_1AZtxr2eZvKYlo2CJDX8whov", "created": 1680651737, "currency": "usd", "evidence": { "access_activity_log": null, "billing_address": null, "cancellation_policy": null, "cancellation_policy_disclosure": null, "cancellation_rebuttal": null, "customer_communication": null, "customer_email_address": null, "customer_name": null, "customer_purchase_ip": null, "customer_signature": null, "duplicate_charge_documentation": null, "duplicate_charge_explanation": null, "duplicate_charge_id": null, "product_description": null, "receipt": null, "refund_policy": null, "refund_policy_disclosure": null, "refund_refusal_explanation": null, "service_date": null, "service_documentation": null, "shipping_address": null, "shipping_carrier": null, "shipping_date": null, "shipping_documentation": null, "shipping_tracking_number": null, "uncategorized_file": null, "uncategorized_text": null }, "evidence_details": { "due_by": 1682294399, "has_evidence": false, "past_due": false, "submission_count": 0 }, "is_charge_refundable": true, "livemode": false, "metadata": {}, "payment_intent": null, "reason": "general", "status": "warning_needs_response"}Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when a charge succeeds, we create a charge. event, and when an invoice payment attempt fails, we create an invoice. event. Certain API requests might create multiple events. For example, if you create a new subscription for a customer, you receive both a customer. event and a charge. event.
Events occur when the state of another API resource changes. The event’s data field embeds the resource’s state at the time of the change. For example, a charge. event contains a charge, and an invoice. event contains an invoice.
As with other API resources, you can use endpoints to retrieve an individual event or a list of events from the API. We also have a separate webhooks system for sending the Event objects directly to an endpoint on your server. You can manage webhooks in your account settings. Learn how to listen for events so that your integration can automatically trigger reactions.
When using Connect, you can also receive event notifications that occur in connected accounts. For these events, there’s an additional account attribute in the received Event object.
We only guarantee access to events through the Retrieve Event API for 30 days.