Manage refunds
[Step 8 of 11] There is no time limit to initiate a refund. You can either issue refunds using Create Refund, or you can manually issue refunds through Seller Central, the account management site for Amazon Pay merchants. Amazon Pay will notify the buyer after a refund has been successfully processed. See buyer communication for more info.
In this step, you will add the ability to issue refunds via API. At the end of this step, you will be able to issue full or partial refunds and check on refund status.
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.
1. Issue a refund
Create Refund to issue a full or partial refund for a successful Charge. You may (at your discretion) also choose to overcompensate the buyer, and refund more than the original Charge amount by either 15% or 75 USD/GBP/EUR or 8,400 YEN (whichever is less).
Request
curl "https://pay-api.amazon.com/:version/refunds/" \
-X POST
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"
-d @request_body
curl "https://pay-api.amazon.com/:environment/:version/refunds/" \
-X POST
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"
-d @request_body
Request body
{
"chargeId": "S01-5105180-3221187-C056351",
"refundAmount": {
"amount": "14.00",
"currencyCode": "USD"
},
"softDescriptor": "Descriptor"
}
Request parameters
Name
|
Location
|
Description
|
x-amz-pay-idempotency-key
(required)
Type: string
|
Header
|
Idempotency key to safely retry requests
|
chargeId
(required)
Type: string
|
Body
|
Charge identifier
|
refundAmount
(required)
Type: price
|
Body
|
Amount to be refunded. Refund amount can be either 15% or 75 USD/GBP/EUR and 8400 JPY (whichever is less) above the captured amount
Maximum value: 150,000 USD/GBP/EUR and 10,000,000 JPY
|
softDescriptor
Type: string
|
Body
|
The description is shown on the buyer payment instrument (such as bank) statement
Default: "AMZ* <MerchantStoreName> amzn.com/pmts"
Max length: 16 characters/bytes
|
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'
);
$payload = array(
'chargeId' => 'S01-5105180-3221187-C056351',
'refundAmount' => array(
'amount' => '14.00',
'currencyCode' => 'USD'
),
'softDescriptor' => 'Descriptor'
);
$headers = array('x-amz-pay-Idempotency-Key' => uniqid());
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->createRefund($payload, $headers);
if ($result['status'] === 201) {
$response = json_decode($result['response'], true);
$refundState = $response['statusDetails']['state'];
$refundId = $response['refundId'];
} 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.Refund;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
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);
}
public void CreateRefund(string chargeId)
{
// prepare the request
var request = new CreateRefundRequest(chargeId, 14.00M, Currency.USD);
// send the request
RefundResponse result = client.CreateRefund(request);
// check if API call was successful
if (!result.Success)
{
// do something, e.g. throw an error
}
}
}
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;
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")
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = null;
JSONObject payload = new JSONObject();
JSONObject refundAmount = new JSONObject();
refundAmount.put("amount", "14.00");
refundAmount.put("currencyCode", "USD");
payload.put("chargeId", "S01-5105180-3221187-C056351");
payload.put("refundAmount", refundAmount);
payload.put("softDescriptor", "Descriptor");
Map<String,String> header = new HashMap<String,String>();
header.put("x-amz-pay-idempotency-key", UUID.randomUUID().toString().replace("-", ""));
response = webstoreClient.createRefund(payload,header);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const uuidv4 = require('uuid/v4');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const payload = {
chargeId: 'S01-5105180-3221187-C056351',
refundAmount: {
amount: '14.00',
currencyCode: 'USD'
},
softDescriptor: 'Descriptor'
};
const headers = {
'x-amz-pay-idempotency-key': uuidv4().toString().replace(/-/g, '')
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.createRefund(payload, headers);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
<?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'
);
$payload = array(
'chargeId' => 'S01-5105180-3221187-C056351',
'refundAmount' => array(
'amount' => '14.00',
'currencyCode' => 'USD'
),
'softDescriptor' => 'Descriptor'
);
$headers = array('x-amz-pay-Idempotency-Key' => uniqid());
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->createRefund($payload, $headers);
if ($result['status'] === 201) {
$response = json_decode($result['response'], true);
$refundState = $response['statusDetails']['state'];
$refundId = $response['refundId'];
} 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.Refund;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
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);
}
public void CreateRefund(string chargeId)
{
// prepare the request
var request = new CreateRefundRequest(chargeId, 14.00M, Currency.USD);
// send the request
RefundResponse result = client.CreateRefund(request);
// check if API call was successful
if (!result.Success)
{
// do something, e.g. throw an error
}
}
}
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;
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")
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = null;
JSONObject payload = new JSONObject();
JSONObject refundAmount = new JSONObject();
refundAmount.put("amount", "14.00");
refundAmount.put("currencyCode", "USD");
payload.put("chargeId", "S01-5105180-3221187-C056351");
payload.put("refundAmount", refundAmount);
payload.put("softDescriptor", "Descriptor");
Map<String,String> header = new HashMap<String,String>();
header.put("x-amz-pay-idempotency-key", UUID.randomUUID().toString().replace("-", ""));
response = webstoreClient.createRefund(payload,header);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const uuidv4 = require('uuid/v4');
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 payload = {
chargeId: 'S01-5105180-3221187-C056351',
refundAmount: {
amount: '14.00',
currencyCode: 'USD'
},
softDescriptor: 'Descriptor'
};
const headers = {
'x-amz-pay-idempotency-key': uuidv4().toString().replace(/-/g, '')
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.createRefund(payload, headers);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
Response
{
"refundId": "S01-5105180-3221187-R022311",
"chargeId": "S01-5105180-3221187-C056351",
"refundAmount": {
"amount": "14.00",
"currencyCode": "USD"
},
"softDescriptor": "Descriptor",
"creationTimestamp": "20190714T155300Z",
"statusDetails": {
"state": "RefundInitiated",
"reasonCode": null,
"reasonDescription": null,
"lastUpdatedTimestamp": "20190714T155300Z"
},
"releaseEnvironment": "Sandbox"
}
2. Check refund status
Get Refund to check Refund status. Amazon Pay processes refunds asynchronously. Either set up Instant Payment Notifications (IPNs), or implement a polling mechanism to query the Get Refund API for updates. See asynchronous processing for more info.
Refund state explanation
Refund status
|
Description
|
RefundInitiated
|
Refund is still pending processing
|
Refunded
|
Refund was successful
|
Declined
|
Refund was declined. Check the reason code for more information:
AmazonRejected - Amazon has rejected the refund, potentially due to a negative balance in your merchant account. To resolve this, you should repay the negative seller balance (NSB) to Amazon, then attempt the refund again or issue a refund to the buyer in an alternate manner (for example, a gift card or store credit).
ProcessingFailure - Amazon could not process the transaction because of an internal processing error, or because the buyer has already received a refund from an A-to-z claim, or a chargeback. You should only retry the refund if the Capture object is in the Completed state. Otherwise, you should refund the buyer in an alternative way (for example, a store credit or a check)
|
Request
curl "https://pay-api.amazon.com/:version/refunds/:refundId" \
-X GET
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
curl "https://pay-api.amazon.com/:environment/:version/refunds/:refundId" \
-X GET
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
Request parameters
Name
|
Location
|
Description
|
refundId
(required)
Type: string
|
Path Parameter
|
Refund identifier
|
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 {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->getRefund('S01-5105180-3221187-R022311');
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$chargeState = $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.Refund;
using Amazon.Pay.API.WebStore.Types;
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);
}
public void GetRefund(string refundId)
{
// send the request
RefundResponse result = client.GetRefund(refundId);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
}
// do something with the result, for instance:
string refundState = result.StatusDetails.State;
}
}
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")
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = webstoreClient.getRefund("S01-5105180-3221187-R022311");
} 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 testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getRefund('S01-5105180-3221187-R022311');
<?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 {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->getRefund('S01-5105180-3221187-R022311');
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$chargeState = $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.Refund;
using Amazon.Pay.API.WebStore.Types;
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);
}
public void GetRefund(string refundId)
{
// send the request
RefundResponse result = client.GetRefund(refundId);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
}
// do something with the result, for instance:
string refundState = result.StatusDetails.State;
}
}
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")
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = webstoreClient.getRefund("S01-5105180-3221187-R022311");
} 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 testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getRefund('S01-5105180-3221187-R022311');
Response
{
"refundId": "S01-5105180-3221187-R022311",
"chargeId": "S01-5105180-3221187-C056351",
"refundAmount": {
"amount": "14.00",
"currencyCode": "USD"
},
"softDescriptor": "Descriptor",
"creationTimestamp": "20190714T155300Z",
"statusDetails": {
"state": "Refunded",
"reasonCode": null,
"reasonDescription": null,
"lastUpdatedTimestamp": "20190714T155300Z"
},
"releaseEnvironment": "Sandbox"
}
