For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
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.
Merchants only have one opportunity to submit evidence. Once a 200 response is received, this information cannot be updated or changed.
Authentication
AuthorizationBasic
Basic authentication of the form Basic <base64(username:password)>.
Path parameters
dispute_idstringRequired
Headers
User-AgentstringOptional
AcceptstringOptional
application/json
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.
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.
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
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.
responseDueBystring
Deadline by which the merchant must respond to the dispute. (Epoch timestamp in seconds, timezone UTC +0.00)
createdAtstring
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.
closingReasonenum
A reason indicating how the final decision on the dispute was reached. Recommended possible values listed in Closing Reasons.
Allowed values:
merchantOrderIdstring
The identifier for the transaction on the merchant side.
transactionDatestring
The timestamp of the order created by the customer. (Epoch timestamp in seconds, timezone UTC +0.00)
settlementAmountstring
The settlementAmount for audit usage.
openingNoteAttachmentslist of strings
Attachments to supplement the openingNote if the customer provided photos or screenshots as part of their dispute description.
updatedAtstring
Timestamp when the dispute was updated. (Epoch timestamp in seconds, timezone UTC +0.00)
closingNotestring
Text describing in detail how the final decision on the dispute was reached. This supplements the closingReason.
metaobject
The extra information for merchants to match payment.
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.
Merchants only have one opportunity to submit evidence. Once a 200 response is received, this information cannot be updated or changed.
