Dispute
For LLMs: see /docs/amazon-pay/llms.txt | Markdown: /amazon-pay-api-v2/dispute.md
Note: If your publicKeyId
does not have an environment prefix (does not begin with 'SANDBOX' or 'LIVE') follow
these instructions instead.
Note: If your publicKeyId has an environment prefix (for example: SANDBOX-AFVX7ULWSGBZ5535PCUQOY7B) follow
these instructions instead.
Supported operations:
Get Dispute - GET https://pay-api.amazon.com/:version/disputes/:disputeIdUpdate Dispute - PATCH https://pay-api.amazon.com/:version/disputes/:disputeIdContest Dispute - POST https://pay-api.amazon.com/:version/disputes/:disputeId/contest
Get Dispute - GET https://pay-api.amazon.eu/:version/disputes/:disputeIdUpdate Dispute - PATCH https://pay-api.amazon.eu/:version/disputes/:disputeIdContest Dispute - POST https://pay-api.amazon.eu/:version/disputes/:disputeId/contest
Get Dispute - GET https://pay-api.amazon.jp/:version/disputes/:disputeIdUpdate Dispute - PATCH https://pay-api.amazon.jp/:version/disputes/:disputeIdContest Dispute - POST https://pay-api.amazon.jp/:version/disputes/:disputeId/contest
Get Dispute - GET https://pay-api.amazon.com/:environment/:version/disputes/:disputeIdUpdate Dispute - PATCH https://pay-api.amazon.com/:environment/:version/disputes/:disputeIdContest Dispute - POST https://pay-api.amazon.com/:environment/:version/disputes/:disputeId/contest
Get Dispute - GET https://pay-api.amazon.eu/:environment/:version/disputes/:disputeIdUpdate Dispute - PATCH https://pay-api.amazon.eu/:environment/:version/disputes/:disputeIdContest Dispute - POST https://pay-api.amazon.eu/:environment/:version/disputes/:disputeId/contest
Get Dispute - GET https://pay-api.amazon.jp/:environment/:version/disputes/:disputeIdUpdate Dispute - PATCH https://pay-api.amazon.jp/:environment/:version/disputes/:disputeIdContest Dispute - POST https://pay-api.amazon.jp/:environment/:version/disputes/:disputeId/contest
Dispute object
Field
Definition
disputeId
Unique identifier
releaseEnvironment
The environment the Dispute object was created in (either Sandbox or Live)
chargeId
Associated charge identifier
disputeTypedisputeType [Enum]
Currently only supports Chargeback
disputeAmountprice
Total disputed amount
filingReasonfilingReason [Enum]
Why dispute was filed (Fraudulent, ProductNotReceived, etc.)
statusDetailsdisputeStatusDetails
Current state, resolution state, resolution reason
merchantEvidencesEvidence >
Evidence provided by merchant
merchantResponseDeadline
Response deadline
resolutionAuthorityresolutionAuthority [Enum]
Party resolving dispute (for example Amazon Pay)
creationTimestamp
Creation date/time (UTC) in ISO 8601
Type: price
Parameter
Description
amount
Transaction amount
currencyCode
Transaction currency code in ISO 4217 format
Type: disputeStatusDetails
Field
Definition
statedisputeState [Enum]
Current state: UnderReview, ActionRequired, Resolved, Closed
reasonCodereasonCode [Enum]
Status reason (see State Transitions)
reasonDescription
Human-readable status explanation
resolutionresolution [Enum]
Outcome: BuyerWon, MerchantWon, NoFault (for Resolved/Closed states)
lastUpdatedTimestamp
Last status change (UTC)
Type: Evidence
Field
Required
Description
Supported Values
evidenceTypeEvidenceType [Enum]
Yes
Category (Receipt, Signature, etc.)
ProductDescription Receipt CancellationPolicy CustomerSignature TrackingNumber CarrierName DeviceId DeviceName DownloadDateTime Other
fileId
No
ID of uploaded evidence file
Any valid file ID
evidenceText
No
Text-based evidence
Free-form text
Enums
disputeType
Value
Description
Chargeback
Payment chargeback dispute
filingReason
Value
Description
ProductNotReceived
Buyer did not receive the product
ProductUnacceptable
Product is unacceptable to buyer (e.g., missing parts)
ProductNoLongerNeeded
Buyer does not need the product anymore
CreditNotProcessed
Buyer returned product but credit was not received
Overcharged
Buyer was overcharged for the product
Fraudulent
Buyer was not responsible for the transaction
SubscriptionCancelled
Buyer was charged after subscription cancellation
DuplicateCharge
Buyer was charged twice for the product
Unrecognized
Buyer does not recognize the charge
Other
Other reason ,Any other reason for dispute filing
disputeState
Value
Description
UnderReview
Investigation ongoing
ActionRequired
Needs merchant/buyer action
Resolved
Decision made (appealable)
Closed
Final state (no changes)
resolution
Value
Description
BuyerWon
Decided in buyer's favor
MerchantWon
Decided in merchant's favor
NoFault
Neither party liable
evidenceType
Value
Description
ProductDescription
Product details and specifications
Receipt
Order receipt document
CancellationPolicy
Cancellation policy document
CustomerSignature
Customer signature document
TrackingNumber
Shipping tracking number
CarrierName
Shipping carrier name
DeviceId
Device identifier for digital goods
DeviceName
Device name for digital goods
DownloadDateTime
Download timestamp for digital goods
Other
Additional evidence types
resolutionAuthority
Value
Description
AmazonPay
Amazon Pay is the authority for Dispute Resolution
Dispute State Transition
State
Description
Resolution
Reason code
UnderReview
Investigation in progress
None
None
ActionRequired
Waiting for merchant or buyer
None
MerchantResponseRequired: Accept or contest disputeMerchantResponseRequired: Accept or contest disputeMerchantAdditionalEvidencesRequired: Provide more evidenceBuyerAdditionalEvidencesRequired: Waiting for buyer evidence
Resolved
Decision made (appealable)
BuyerWon
MerchantAcceptedDispute: Merchant accepted MerchantResponseDeadlineExpired: Response deadline passed InvestigatorResolved: Investigation complete
Resolved
Decision made (appealable)
MerchantWon
BuyerCancelled: Buyer cancelled dispute InvestigatorResolved: Investigation complete ChargebackFiled: Buyer has filed chargeback besides Amazon Pay A-to-z Guarantee claim.
Closed
Final state (no changes)
BuyerWon
Same as Resolved state
Closed
Final state (no changes)
MerchantWon
Same as Resolved state
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 this API call when you need to review specific dispute details, track dispute status, or gather information for dispute resolution.
Request
curl "https://pay-api.amazon.com/v2/disputes/:disputeId" \
curl "https://pay-api.amazon.com/:environment/v2/disputes/:disputeId" \
Sample Code
<?php
include 'vendor/autoload.php';
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
try {
$disputeId = 'S01-0000000-0000000-B000000';
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->getDispute($disputeId);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$disputeState = $response['statusDetails']['state'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Dispute;
using Amazon.Pay.API.WebStore.Types;
using System;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void GetDispute(string disputeId)
{
// send the request
DisputeResponse result = client.GetDispute(disputeId);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Console.WriteLine(result.RawResponse);
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Region;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = webstoreClient.getDispute("S01-0000000-0000000-B000000");
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const disputeId = 'S01-0000000-0000000-B000000';
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getDispute(disputeId);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
require 'amazon-pay-api-sdk-ruby'
config = {
region: 'YOUR_REGION_CODE', # Supported values: na, eu, jp
public_key_id: 'YOUR_PUBLIC_KEY_ID',
private_key: File.read('privateKey.pem')
}
client = AmazonPayClient.new(config)
dispute_id = 'S01-0000000-0000000-B000000'
response = client.get_dispute(dispute_id)
if response.code.to_i == 200
puts response.body
else
# check the error
puts "status=#{response.code}"
puts response.body
end
<?php
include 'vendor/autoload.php';
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'sandbox' => true,
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
try {
$disputeId = 'S01-0000000-0000000-B000000';
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->getDispute($disputeId);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$disputeState = $response['statusDetails']['state'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Dispute;
using Amazon.Pay.API.WebStore.Types;
using System;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
environment: Environment.Sandbox,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void GetDispute(string disputeId)
{
// send the request
DisputeResponse result = client.GetDispute(disputeId);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Console.WriteLine(result.RawResponse);
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Environment;
import com.amazon.pay.api.types.Region;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = webstoreClient.getDispute("S01-0000000-0000000-B000000");
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
sandbox: true,
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const disputeId = 'S01-0000000-0000000-B000000';
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getDispute(disputeId);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
require 'amazon-pay-api-sdk-ruby'
config = {
region: 'YOUR_REGION_CODE', # Supported values: na, eu, jp
public_key_id: 'YOUR_PUBLIC_KEY_ID',
private_key: File.read('privateKey.pem'),
sandbox: true
}
client = AmazonPayClient.new(config)
dispute_id = 'S01-0000000-0000000-B000000'
response = client.get_dispute(dispute_id)
if response.code.to_i == 200
puts response.body
else
# check the error
puts "status=#{response.code}"
puts response.body
end
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"
}
Error codes
Amazon Pay APIs return standard HTTP status codes and error responses. For a complete list of error codes, response formats, and handling guidelines, see the Error Handling documentation
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
curl "https://pay-api.amazon.com/v2/disputes/:disputeId" \
curl "https://pay-api.amazon.com/:environment/v2/disputes/:disputeId" \
Request body
{
"statusDetails": {
"resolution": "BuyerWon",
"state": "Resolved",
"reasonCode": "MerchantAcceptedDispute",
"reasonDescription": "Merchant accepted the dispute request"
},
"closureTimestamp": "20190716T162300Z"
}
Request parameters
Name
Location
Description
StatusDetails(required) DisputeStatusDetails
Body
Specifies the dispute state (Resolved/Closed), resolution (BuyerWon/MerchantWon/NoFault), and reason code. All fields required.
ClosureTimeStamp(required)
Body
Required for "Closed" state only. UTC timestamp in ISO 8601 format.
Sample Code
<?php
include 'vendor/autoload.php';
use Amazon\Pay\API\Constants\DisputeResolution;
use Amazon\Pay\API\Constants\DisputeState;
use Amazon\Pay\API\Constants\DisputeReasonCode;
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
$disputeId = 'S01-0000000-0000000-B000000';
$closureTimestamp = time();
$payload = array(
'statusDetails' => array(
'resolution' => DisputeResolution::MERCHANT_WON,
'state' => DisputeState::RESOLVED,
'reasonCode' => DisputeReasonCode::MERCHANT_ACCEPTED_DISPUTE,
'reasonDescription' => 'Merchant accepted the dispute request'
),
'closureTimestamp' => $closureTimestamp
);
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->updateDispute($disputeId, $payload);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$disputeState = $response['statusDetails']['state'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Dispute;
using Amazon.Pay.API.WebStore.Types;
using System;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void UpdateDispute(string disputeId)
{
// prepare the request
var request = new UpdateDisputeRequest(
state: "Resolved",
reasonCode: "MerchantAcceptedDispute",
closureTimestamp: DateTime.UtcNow,
reasonDescription: "Merchant accepted the dispute request",
resolution: "MerchantWon"
);
// send the request
DisputeResponse result = client.UpdateDispute(disputeId, request);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Console.WriteLine(result.RawResponse);
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.DisputeReasonCode;
import com.amazon.pay.api.types.DisputeResolution;
import com.amazon.pay.api.types.DisputeState;
import com.amazon.pay.api.types.Region;
import org.json.JSONObject;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
String disputeId = "S01-0000000-0000000-B000000";
JSONObject statusDetails = new JSONObject();
statusDetails.put("resolution", DisputeResolution.MERCHANT_WON.getDisputeResolution());
statusDetails.put("state", DisputeState.RESOLVED.getDisputeState());
statusDetails.put("reasonCode", DisputeReasonCode.MERCHANT_ACCEPTED_DISPUTE.getDisputeReasonCode());
statusDetails.put("reasonDescription", "Merchant accepted the dispute request");
JSONObject payload = new JSONObject();
payload.put("statusDetails", statusDetails);
// Current Unix timestamp (seconds since epoch)
payload.put("closureTimestamp", System.currentTimeMillis() / 1000L);
AmazonPayResponse response = webstoreClient.updateDispute(disputeId, payload);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const disputeId = 'S01-0000000-0000000-B000000';
const payload = {
statusDetails: {
resolution: "MerchantWon",
state: "Resolved",
reasonCode: "MerchantAcceptedDispute",
reasonDescription: "Merchant accepted the dispute request"
},
closureTimestamp: Date.now()
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateDispute(disputeId, payload);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
require 'amazon-pay-api-sdk-ruby'
config = {
region: 'YOUR_REGION_CODE', # Supported values: na, eu, jp
public_key_id: 'YOUR_PUBLIC_KEY_ID',
private_key: File.read('privateKey.pem')
}
client = AmazonPayClient.new(config)
dispute_id = 'S01-0000000-0000000-B000000'
payload = {
"statusDetails": {
"resolution": "MerchantWon",
"state": "Resolved",
"reasonCode": "MerchantAcceptedDispute",
"reasonDescription": "Merchant accepted the dispute request"
},
"closureTimestamp": Time.now.to_i
}
response = client.update_dispute(dispute_id, payload)
if response.code.to_i == 200
puts response.body
else
# check the error
puts "status=#{response.code}"
puts response.body
end
<?php
include 'vendor/autoload.php';
use Amazon\Pay\API\Constants\DisputeResolution;
use Amazon\Pay\API\Constants\DisputeState;
use Amazon\Pay\API\Constants\DisputeReasonCode;
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'sandbox' => true,
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
$disputeId = 'S01-0000000-0000000-B000000';
$closureTimestamp = time();
$payload = array(
'statusDetails' => array(
'resolution' => DisputeResolution::MERCHANT_WON,
'state' => DisputeState::RESOLVED,
'reasonCode' => DisputeReasonCode::MERCHANT_ACCEPTED_DISPUTE,
'reasonDescription' => 'Merchant accepted the dispute request'
),
'closureTimestamp' => $closureTimestamp
);
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->updateDispute($disputeId, $payload);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$disputeState = $response['statusDetails']['state'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Dispute;
using Amazon.Pay.API.WebStore.Types;
using System;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
environment: Environment.Sandbox,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void UpdateDispute(string disputeId)
{
// prepare the request
var request = new UpdateDisputeRequest(
state: "Resolved",
reasonCode: "MerchantAcceptedDispute",
closureTimestamp: DateTime.UtcNow,
reasonDescription: "Merchant accepted the dispute request",
resolution: "MerchantWon"
);
// send the request
DisputeResponse result = client.UpdateDispute(disputeId, request);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Console.WriteLine(result.RawResponse);
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.DisputeReasonCode;
import com.amazon.pay.api.types.DisputeResolution;
import com.amazon.pay.api.types.DisputeState;
import com.amazon.pay.api.types.Environment;
import com.amazon.pay.api.types.Region;
import org.json.JSONObject;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
String disputeId = "S01-0000000-0000000-B000000";
JSONObject statusDetails = new JSONObject();
statusDetails.put("resolution", DisputeResolution.MERCHANT_WON.getDisputeResolution());
statusDetails.put("state", DisputeState.RESOLVED.getDisputeState());
statusDetails.put("reasonCode", DisputeReasonCode.MERCHANT_ACCEPTED_DISPUTE.getDisputeReasonCode());
statusDetails.put("reasonDescription", "Merchant accepted the dispute request");
JSONObject payload = new JSONObject();
payload.put("statusDetails", statusDetails);
// Current Unix timestamp (seconds since epoch)
payload.put("closureTimestamp", System.currentTimeMillis() / 1000L);
AmazonPayResponse response = webstoreClient.updateDispute(disputeId, payload);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
sandbox: true,
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const disputeId = 'S01-0000000-0000000-B000000';
const payload = {
statusDetails: {
resolution: "MerchantWon",
state: "Resolved",
reasonCode: "MerchantAcceptedDispute",
reasonDescription: "Merchant accepted the dispute request"
},
closureTimestamp: Date.now()
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateDispute(disputeId, payload);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
require 'amazon-pay-api-sdk-ruby'
config = {
region: 'YOUR_REGION_CODE', # Supported values: na, eu, jp
public_key_id: 'YOUR_PUBLIC_KEY_ID',
private_key: File.read('privateKey.pem'),
sandbox: true
}
client = AmazonPayClient.new(config)
dispute_id = 'S01-0000000-0000000-B000000'
payload = {
"statusDetails": {
"resolution": "MerchantWon",
"state": "Resolved",
"reasonCode": "MerchantAcceptedDispute",
"reasonDescription": "Merchant accepted the dispute request"
},
"closureTimestamp": Time.now.to_i
}
response = client.update_dispute(dispute_id, payload)
if response.code.to_i == 200
puts response.body
else
# check the error
puts "status=#{response.code}"
puts response.body
end
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"
}
Error codes
Amazon Pay APIs return standard HTTP status codes and error responses. For a complete list of error codes, response formats, and handling guidelines, see the Error Handling documentation .
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
curl "https://pay-api.amazon.com/v2/disputes/:disputeId/contest" \
curl "https://pay-api.amazon.com/:environment/v2/disputes/:disputeId/contest" \
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) Evidence >
Body
List of evidence items supporting your case Each evidence item needs either fileId or evidenceText See Evidence Types table for supported values
Sample Code
<?php
include 'vendor/autoload.php';
use Amazon\Pay\API\Constants\EvidenceType;
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
$disputeId = 'S01-0000000-0000000-B000000';
$payload = array(
'merchantEvidences' => array(
array(
'evidenceType' => EvidenceType::TRACKING_NUMBER,
'fileId' => 'YOUR_FILE_ID',
'evidenceText' => 'raw text supporting merchant evidence'
)
)
);
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->contestDispute($disputeId, $payload);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$disputeState = $response['statusDetails']['state'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Dispute;
using Amazon.Pay.API.WebStore.Types;
using System;
using System.Collections.Generic;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void ContestDispute(string disputeId)
{
// prepare the request
var merchantEvidences = new List<MerchantEvidence>
{
new MerchantEvidence
{
EvidenceType = "TrackingNumber",
FileId = "YOUR_FILE_ID",
EvidenceText = "raw text supporting merchant evidence"
}
};
var request = new ContestDisputeRequest(merchantEvidences);
// send the request
DisputeResponse result = client.ContestDispute(disputeId, request);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Console.WriteLine(result.RawResponse);
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.EvidenceType;
import com.amazon.pay.api.types.Region;
import org.json.JSONObject;
// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
String disputeId = "S01-0000000-0000000-B000000";
JSONObject evidence = new JSONObject();
evidence.put("evidenceType", EvidenceType.TRACKING_NUMBER.getEvidenceType());
evidence.put("fileId", "YOUR_FILE_ID");
evidence.put("evidenceText", "raw text supporting merchant evidence");
JSONObject payload = new JSONObject();
payload.append("merchantEvidences", evidence);
Map<String, String> header = new HashMap<String, String>();
header.put("x-amz-pay-idempotency-key", UUID.randomUUID().toString().replace("-", ""));
AmazonPayResponse response = webstoreClient.contestDispute(disputeId, payload, header);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const disputeId = 'S01-0000000-0000000-B000000';
const payload = {
merchantEvidences: [
{
evidenceType: "TrackingNumber",
fileId: "YOUR_FILE_ID",
evidenceText: "raw text supporting merchant evidence"
}
]
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.contestDispute(disputeId, payload);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
require 'amazon-pay-api-sdk-ruby'
config = {
region: 'YOUR_REGION_CODE', # Supported values: na, eu, jp
public_key_id: 'YOUR_PUBLIC_KEY_ID',
private_key: File.read('privateKey.pem')
}
client = AmazonPayClient.new(config)
dispute_id = 'S01-0000000-0000000-B000000'
payload = {
"merchantEvidences": [
{
"evidenceType": "TrackingNumber",
"fileId": "YOUR_FILE_ID",
"evidenceText": "raw text supporting merchant evidence"
}
]
}
response = client.contest_dispute(dispute_id, payload)
if response.code.to_i == 200
puts response.body
else
# check the error
puts "status=#{response.code}"
puts response.body
end
<?php
include 'vendor/autoload.php';
use Amazon\Pay\API\Constants\EvidenceType;
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'sandbox' => true,
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
$disputeId = 'S01-0000000-0000000-B000000';
$payload = array(
'merchantEvidences' => array(
array(
'evidenceType' => EvidenceType::TRACKING_NUMBER,
'fileId' => 'YOUR_FILE_ID',
'evidenceText' => 'raw text supporting merchant evidence'
)
)
);
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->contestDispute($disputeId, $payload);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$disputeState = $response['statusDetails']['state'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Dispute;
using Amazon.Pay.API.WebStore.Types;
using System;
using System.Collections.Generic;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
environment: Environment.Sandbox,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void ContestDispute(string disputeId)
{
// prepare the request
var merchantEvidences = new List<MerchantEvidence>
{
new MerchantEvidence
{
EvidenceType = "TrackingNumber",
FileId = "YOUR_FILE_ID",
EvidenceText = "raw text supporting merchant evidence"
}
};
var request = new ContestDisputeRequest(merchantEvidences);
// send the request
DisputeResponse result = client.ContestDispute(disputeId, request);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Console.WriteLine(result.RawResponse);
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Environment;
import com.amazon.pay.api.types.EvidenceType;
import com.amazon.pay.api.types.Region;
import org.json.JSONObject;
// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
String disputeId = "S01-0000000-0000000-B000000";
JSONObject evidence = new JSONObject();
evidence.put("evidenceType", EvidenceType.TRACKING_NUMBER.getEvidenceType());
evidence.put("fileId", "YOUR_FILE_ID");
evidence.put("evidenceText", "raw text supporting merchant evidence");
JSONObject payload = new JSONObject();
payload.append("merchantEvidences", evidence);
Map<String, String> header = new HashMap<String, String>();
header.put("x-amz-pay-idempotency-key", UUID.randomUUID().toString().replace("-", ""));
AmazonPayResponse response = webstoreClient.contestDispute(disputeId, payload, header);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
sandbox: true,
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const disputeId = 'S01-0000000-0000000-B000000';
const payload = {
merchantEvidences: [
{
evidenceType: "TrackingNumber",
fileId: "YOUR_FILE_ID",
evidenceText: "raw text supporting merchant evidence"
}
]
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.contestDispute(disputeId, payload);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
require 'amazon-pay-api-sdk-ruby'
config = {
region: 'YOUR_REGION_CODE', # Supported values: na, eu, jp
public_key_id: 'YOUR_PUBLIC_KEY_ID',
private_key: File.read('privateKey.pem'),
sandbox: true
}
client = AmazonPayClient.new(config)
dispute_id = 'S01-0000000-0000000-B000000'
payload = {
"merchantEvidences": [
{
"evidenceType": "TrackingNumber",
"fileId": "YOUR_FILE_ID",
"evidenceText": "raw text supporting merchant evidence"
}
]
}
response = client.contest_dispute(dispute_id, payload)
if response.code.to_i == 200
puts response.body
else
# check the error
puts "status=#{response.code}"
puts response.body
end
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
}
]
}
Error codes
Amazon Pay APIs return standard HTTP status codes and error responses. For a complete list of error codes, response formats, and handling guidelines, see the Error Handling documentation .
