Sign In
Sign In

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*&lt;MerchantStoreName&gt; 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.