Refund
A Refund allows you (the merchant) to refund some or all of a previously-captured Charge to the buyer. A refund can only be initiated on a previously-captured Charge, and multiple Refunds can be initiated on a single Charge.
Amazon Pay processes refunds asynchronously. Refunds start in a Pending state before moving to a Completed or Declined state, depending on whether or not the operation was successful. You must set up instant payment notifications (IPNs), or implement a polling mechanism to query Get Refund API for updates. See asynchronous processing for more information.
Supported operations
- Create Refund - POST https://pay-api.amazon.com/:environment/:version/refunds/
- Get Refund - GET https://pay-api.amazon.com/:environment/:version/refunds/:refundId
- Create Refund - POST https://pay-api.amazon.eu/:environment/:version/refunds/
- Get Refund - GET https://pay-api.amazon.eu/:environment/:version/refunds/:refundId
- Create Refund - POST https://pay-api.amazon.jp/:environment/:version/refunds/
- Get Refund - GET https://pay-api.amazon.jp/:environment/:version/refunds/:refundId
Refund object
| Parameter
|
Description
|
| refundId Type: string |
Refund identifier |
| chargeId Type: string |
Charge identifier |
| refundAmount Type: price |
Amount to be refunded. Refund amount can be either 15% or 75 USD/GBP/EUR (whichever is less) above the captured amount Maximum value: 150,000 USD/GBP/EUR |
| softDescriptor Type: string |
Description shown on the buyer payment instrument statement The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor here>" Max length: 16 characters |
| creationTimestamp Type: dateTime |
UTC date and time when the refund was created in ISO 8601 format
|
| statusDetail Type: statusDetail |
State of the refund object
|
| releaseEnvironment Type: string |
The environment the Refund object was created in (either Sandbox or Live)
|
Type: price
| Parameter
|
Description
|
| amount Type: string |
Transaction amount
|
| currencyCode Type: string |
Transaction currency code in ISO 4217 format Example: USD |
Type: statusDetail
| Parameter
|
Description
|
| state Type: string |
Current object state
|
| reasonCode Type: string |
Reason code for current state
|
| reasonDescription Type: string |
An optional description of the refund state
|
| lastUpdatedTimestamp Type: dateTime |
UTC date and time when the state was created in ISO 8601 format
|
States and reason code
| State
|
Description
|
Reason code
|
| RefundInitiated
|
A Refund object is in Pending state until it is processed by Amazon Allowed operation: GET Refund |
-
|
| Declined
|
Amazon has declined the refund because maximum amount has been refunded or there was some other issue Allowed operation: GET Refund |
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) |
| Refunded
|
Refund request has been processed and funds will be refunded to the buyer Allowed operation: GET Refund |
-
|
Operations
Create Refund
Initiate a full or partial refund for a charge. At your discretion, you can 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). The response for Create Refund will include a Refund ID. This is the only time this value will ever be returned. You must store the ID in order to retrieve Refund details at a later date.
Request
curl "https://pay-api.amazon.com/:environment/:version/refunds/" \
-X POST
-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-d @request_body
Request body
{
"chargeId": "CHARGE_ID",
"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 (whichever is less) above the captured amount Maximum value: 150,000 USD/GBP/EUR |
| 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 |
Response
Returns HTTP 201 (Created) status if the operation was successful. Subsequent retry attempts using the same Idempotency Key may return a HTTP 200 (OK) status if a new resource is not created.
{
"refundId": "S01-5105180-3221187-R022311",
"chargeId": "S01-5105180-3221187-C056351",
"refundAmount": {
"amount": "14.00",
"currencyCode": "USD"
},
"softDescriptor": "Descriptor",
"creationTimestamp": "20190714T155300Z",
"statusDetail": {
"state": "Pending",
"reasonCode": null,
"reasonDescription": null,
"lastUpdatedTimestamp": "20190714T155300Z"
}
}
Error codes
| HTTP status code
|
Reason code
|
Description
|
| 400 BAD_REQUEST
|
TransactionAmountExceeded
|
You've exceeded the maximum refund amount allowed for this Refund
|
| 422 UNPROCESSABLE_ENTITY
|
InvalidChargeStatus
|
You tried to call a Refund operation on a Charge that is not in a Completed state. Check the Charge status for more information
|
| 422 UNPROCESSABLE_ENTITY
|
TransactionCountExceeded
|
You've exceeded the maximum limit of 10 Refunds per Charge
|
| 422 UNPROCESSABLE_ENTITY
|
AmazonRejected
|
Amazon has rejected the refund. You should issue a refund to the buyer in an alternate manner (for example, a gift card or store credit)
|
| 500 INTERNAL_SERVER_ERROR
|
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 Charge object is in the Captured state. Otherwise, you should refund the buyer in an alternative way (for example, a store credit or a check)
|
Generic errors can be found here .
Get Refund
Get refund details.
Request
curl "https://pay-api.amazon.com/:environment/:version/refunds/:refundId" \
-X GET
-H "authorization: Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
Request parameters
| Name
|
Location
|
Description
|
| refundId (required) Type: string |
Path Parameter
|
Refund identifier
|
Response
Returns HTTP 200 (OK) status if the operation was successful.
{
"refundId": "S01-5105180-3221187-R022311",
"chargeId": "S01-5105180-3221187-C056351",
"refundAmount":{
"amount": "14.00",
"currencyCode": "USD"
},
"softDescriptor": "Descriptor",
"creationTimestamp": "20190714T155300Z",
"statusDetail":{
"state": "Refunded",
"reasonCode": null,
"reasonDescription": null,
"lastUpdatedTimestamp": "20190714T155300Z"
}
}
Error codes
Generic errors can be found here.