The Respond to the Dispute endpoint allows a merchant to submit evidence for the dispute. This is only allowed if the dispute is the state `needs_response`.
Evidence fields are submitted directly in the request body alongside the dispute `id`. At least one evidence field must be provided.
A successful response submits the merchant's challenge immediately and changes the dispute status to `under_review`. There is no separate finalize step.
Merchants only have one opportunity to submit evidence. Once a 200 response is received, this information cannot be updated or changed.
Request
This endpoint expects an object.
idstringOptional
A unique ID given to a dispute.
productDescriptionstringOptional<=5000 characters
A description of the product or service and any relevant details on how this was presented to the customer at the time of purchase.
refundPolicystringOptionalformat: "binary"
Token of the file upload. The merchant's refund policy, as shown or provided to the customer.
refundPolicyDisclosurestringOptional<=5000 characters
An explanation of how and when the customer was shown or provided with the merchant's refund policy prior to purchase.
refundRefusalExplanationstringOptional<=5000 characters
The merchant's explanation for why the customer is not entitled to a refund.
shippingDocumentationstringOptionalformat: "binary"
Token of the file upload. A shipping label or receipt for the disputed payment.
shippingAddressstringOptional<=5000 characters
The address to which a physical product was shipped.
shippingDatestringOptional<=5000 characters
In cases of physical products, the date that a physical product began its route to the shipping address in a clear human-readable format. This date should be prior to the date of the dispute.
shippingCarrierstringOptional<=5000 characters
In cases of physical products, the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, separate them with commas.
shippingTrackingNumberstringOptional<=5000 characters
The tracking number for a physical product, obtained from the delivery service.
uncategorizedFilestringOptionalformat: "binary"
Token of the file upload. Additional file that's not in any of the categories above.
uncategorizedTextstringOptional<=5000 characters
Any additional text deemed relevant by the merchant.
Response
When successful, returns the updated dispute object
idstring
Dispute identifier
orderstring
The token of the order that the dispute is for.
amountstring
The amount of the dispute
currencystring
The ISO 4217 currency code of the dispute.
reasonenum
The reason for the dispute.
statusenum
The current state of the dispute. Values depend on how the dispute state machine is modeled.
openbooleanDefaults to true
True if a final decision on the dispute hasn’t been made yet.
responseDueByinteger
Deadline by which the merchant must respond to the dispute. (Epoch timestamp in seconds, timezone UTC +0.00)
createdAtinteger
A timestamp indicating when the dispute was created. (Epoch timestamp in seconds, timezone UTC +0.00)
openingNotestring
Text from the customer describing why the dispute was opened or the reason for the complaint. While dispute category codes are helpful at informing what a merchant should present, it doesn’t provide reasoning behind the customer’s complaint. In some cases, this can help merchants troubleshoot the dispute directly with their customers.
openingNoteAttachmentslist of stringsOptional
Attachments to supplement the openingNote if the customer provided photos or screenshots as part of their dispute description.
updatedAtintegerOptional
Timestamp when the dispute was updated. (Epoch timestamp in seconds, timezone UTC +0.00)
closingReasonenumOptional
A reason indicating how the final decision on the dispute was reached. Recommended possible values listed in Closing Reasons.
closingNotestringOptional
Text describing in detail how the final decision on the dispute was reached. This supplements the closingReason.
merchantOrderIdstringOptional
The identifier for the transaction on the merchant side.
transactionDateintegerOptional
The timestamp of the order created by the customer. (Epoch timestamp in seconds, timezone UTC +0.00)
settlementAmountstringOptional
The settlementAmount for audit usage.
partialRefundAmountstringOptional
The amount partially refunded for the disputed order, if applicable.
metaobjectOptional
The extra information for merchants to match payment.
