--- title: Manage disputes url: amazon-pay-buy-now-checkout/manage-disputes.html --- **[Step 6 of 8]** Buyers can create a dispute by filing a chargeback with their bank. The methods invoke the dispute management process, which you can handle programmatically through the Dispute API instead of Seller Central. You can retrieve dispute details, submit evidence, track status, and respond to chargebacks through API endpoints. * TOC {:toc} {::options toc_levels="3" /} *** ### Flow Diagram for Merchant Integration with Dispute APIs ### Receiving Dispute Notifications When a dispute is created or its status changes, Amazon Pay sends an Instant Payment Notification (IPN) to your configured endpoint. The IPN message includes: ``` { "MerchantID": "Your merchant identifier", "ObjectType": "CHARGEBACK", "ObjectId": "S01-0000000-0000000-B000000", "ChargePermissionId": "S01-0000000-0000000", "NotificationType": "STATE_CHANGE", "NotificationId": "9b4155a0-c396-46d0-83f7-te1st2xx1234", "NotificationVersion": "V2" } ``` View the full chargeback IPN notification details. ### Get Dispute Details Get detailed information about a specific dispute by providing its unique dispute ID. This endpoint returns comprehensive dispute data including the dispute type, amount, status, and any associated evidence or documentation. Use Get Dispute API call when you need to review specific dispute details, track dispute status, or gather information for dispute resolution. #### Request #### Response Format The API returns a Dispute object containing: * Basic dispute information (ID, type, amount, filing reason) * Transaction details (charge ID, timestamps) * Status information (state, resolution, reason codes) * Evidence submissions (merchant documentation and files) ``` { "disputeId": "P01-1111111-1111111-B123456", "chargeId": "P01-1111111-1111111-C123456", "disputeType": "Chargeback", "disputeAmount": { "amount": "400", "currencyCode": "USD" }, "filingReason": "Fraudulent", "filingTimestamp": "20190714T155300Z", "resolutionAuthority": "AmazonPay", "statusDetails": { "state": "Resolved", "reasonCode": "MerchantAcceptedDispute", "reasonDescription": "Merchant accepted the dispute request", "resolution": "BuyerWon", "lastUpdatedTimestamp": "20190716T156500Z" }, "resolutionAuthority": "AmazonPay", "merchantEvidences": [ { "evidenceType" : "TrackingNumber", "fileId" : null, "evidenceText": "raw text supporting merchant evidence" }, { "evidenceType": "CustomerSignature", "fileId": "customer_signature_file_id", "evidenceText": null } ], "closureTimestamp": "20190716T155300Z", "releaseEnvironment": "Live" } ``` ### Update Dispute Details Submit your response through the Update Dispute API to accept a dispute when you agree the customer's chargeback is valid. #### Request #### Request body ``` { "statusDetails": { "resolution": "BuyerWon", "state": "Resolved", "reasonCode": "MerchantAcceptedDispute", "reasonDescription": "Merchant accepted the dispute request" }, "closureTimestamp": "20190716T162300Z" } ``` #### Request parameters
Name
Location
Description
StatusDetails
(required)

Type: DisputeStatusDetails
Body
Specifies the dispute state (Resolved/Closed), resolution (BuyerWon/MerchantWon/NoFault), and reason code. All fields required.
ClosureTimeStamp
(required)

Type: dateTime
Body
Required for "Closed" state only. UTC timestamp in ISO 8601 format.
#### Response The API returns an updated Dispute object containing: * Basic dispute information (ID, type, amount, filing reason) * Transaction details (charge ID, timestamps) * Updated status information (state, resolution, reason codes) * Evidence submissions (merchant documentation and files) ``` { "disputeId": "P01-1111111-1111111-B123456", "chargeId": "P01-1111111-1111111-C123456", "disputeType": "Chargeback", "disputeAmount": { "amount": "400", "currencyCode": "USD" }, "filingReason": "Fraudulent", "filingTimestamp": "20190714T155300Z", "resolutionAuthority": "AmazonPay", "statusDetails": { "state": "Resolved", "reasonCode": "MerchantAcceptedDispute", "reasonDescription": "Merchant accepted the dispute request", "resolution": "BuyerWon", "lastUpdatedTimestamp": "20190716T156500Z" }, "resolutionAuthority": "AmazonPay", "closureTimestamp": "20190716T155300Z", "releaseEnvironment": "Live" } ``` ### Contest Dispute Details Challenge a dispute by submitting evidence and documentation to support your case against the chargeback. This endpoint enables merchants to formally contest a dispute by providing relevant proof such as shipping confirmations, customer communications, or product documentation. Use the Contest Dispute API call when you have valid grounds to dispute a customer's chargeback and want to submit supporting evidence for review. #### Request #### Request body ``` { "merchantEvidences": [ { "evidenceType" : "TrackingNumber", "fileId": null, "evidenceText": "raw text supporting merchant evidence" }, { "evidenceType": "CustomerSignature", "fileId": "customer_signature_file_id", "evidenceText": null } ] } ``` #### Request parameters
Name
Location
Description
merchantEvidences
(required)

Type: list <Evidence >
Body
List of evidence items supporting your case

  • Each evidence item needs either fileId or evidenceText
  • See Evidence Types table for supported values
#### Response The API returns an updated Dispute object: ``` { "disputeId": "P01-1111111-1111111-B123456", "chargeId": "P01-1111111-1111111-C123456", "disputeType": "Claim", "disputeAmount": { "amount": "400", "currencyCode": "USD" }, "filingReason": "ProductNotReceived", "filingTimestamp": "20190714T155300Z", "statusDetails": { "state": "UnderReview", "reasonCode": null, "reasonDescription": null, "resolution": null, "lastUpdatedTimestamp": "20190714T156500Z" }, "resolutionAuthority": "AmazonPay", "releaseEnvironment": "Live", "merchantEvidences": [ { "evidenceType" : "TrackingNumber", "fileId" : null, "evidenceText": "raw text supporting merchant evidence" }, { "evidenceType": "CustomerSignature", "fileId": "customer_signature_file_id", "evidenceText": null } ] } ``` ### Attach Evidence to Disputes Add supporting documentation and evidence files to an existing dispute case. This endpoint allows you to upload various types of evidence such as receipts, delivery confirmations, customer correspondence, or product photos to strengthen your dispute response. Use Attach Evidence API call when you need to supplement your dispute case with additional documentation, either during initial submission or as follow-up evidence. #### Request #### Request body ``` { "merchantEvidences" : [ { "evidenceType" : "Receipt", "fileId": "receipt_file_id", "evidenceText" : "null", } ] } ``` #### Request parameters
Name
Location
Description
merchantEvidences
(required)

Type: list < Evidence>
Body
List of evidence items supporting your case

  • evidenceType: Type of evidence (Receipt, TrackingNumber, CustomerSignature)
  • fileId: Unique identifier for uploaded file
  • evidenceText: Supporting text (when applicable)
#### Response The API returns an updated Dispute object containing: * Basic dispute information (ID, type, amount, filing reason) * Transaction details (charge ID, timestamps) * Updated status information (state, resolution, reason codes) * Evidence submissions (merchant documentation and files) ``` { "disputeId": " P01-1111111-1111111-B123456", // APay dispute ID generated from request "chargeId": "P01-1111111-1111111-C123456", "disputeType" : "Chargeback", "disputeAmount": { "amount": "400", "currencyCode": "USD" }, "filingReason": "ProductNotReceived", "filingTimestamp": 20190714T155300Z, "statusDetails": { "state": "UnderReview", "reasonCode": null, "reasonDescription" : null "resolution": null, "lastUpdatedTimestamp": 20190714T156500Z }, "resolutionAuthority": "AmazonPay", "releaseEnvironment": "Live", "merchantEvidences" : [ { "evidenceType" : "TrackingNumber", "fileId": null, "evidenceText" : "raw text supporting merchant evidence", }, { "evidenceType" : "CustomerSignature", "fileId" : "customer_signature_file_id", "evidenceText": null }, { "evidenceType" : "Receipt", "fileId": receipt_file_id, "evidenceText" : "null", } ] } ``` ### Upload files Upload and manage files for dispute evidence and other documentation needs. The Upload File API supports common file formats and provides secure upload URLs. The API provides a two-step process to upload files securely. #### Step 1: Get Upload URL First, request a secure upload URL: #### Request #### Request body ``` { "type" : "jpg", "purpose" : "disputeEvidence" } ``` #### Request parameters
Name
Location
Description
x-amz-pay-idempotency-key
(required)

Type: String
Header
Unique key to prevent duplicate uploads. For detailed guidance on creating and using idempotency keys, see Idempotency.
type

Type: String
Body
File format (jpg, png, pdf)
purpose

Type: String
Body
Upload reason (disputeEvidence)
#### Supported file types
fileType
 Description
 Content-Type
csv
 CSV files
 text/csv
pdf
 PDF documents
 application/pdf
xls/xlsx
 Excel spreadsheets
 application/vnd.ms-excel (xls)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (xlsx)
doc/docx
 Word documents
 application/msword (doc)
application/vnd.openxmlformats-officedocument.wordprocessingml.document (docx)
ods
 OpenDocument spreadsheets
 application/vnd.oasis.opendocument.spreadsheet
jpg/png
 Image files
 image/jpeg (jpg)
image/png (png)
#### Response The API returns: ``` { "id": "file_sdcjscbjckndjhckj", "type" : "jpg", "purpose": "disputeEvidence", "uploadTimestamp": "20190714T155300Z", "url": "https://pay-api.amazon.com/v1/files/file_sdcjscbjckndjhckj/contents", "urlExpirationTimeStamp": "20190714T155300Z" } ``` #### Step 2: Upload your file Send your file to the returned URL: curl "YOUR_PRESIGNED_URL" \
-X PUT \
-H "Content-Type: application/pdf" \
-T "/path/to/file"
File Requirements: * Maximum size: 2MB * Files must be relevant dispute evidence After uploading, use the returned fileId when submitting dispute evidence.