--- title: Refund url: amazon-pay-api-v2/v1-refund.html --- 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

--- * TOC {:toc} {::options toc_levels="3" /} *** ### 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](../amazon-pay-api-v2/v1-idempotency.html) 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](https://restfulapi.net/http-status-200-ok/) . ### 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](../amazon-pay-api-v2/v1-error-handling.html). ### Related topics - [Charge object](../amazon-pay-api-v2/v1-charge.html)