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


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 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
Description shown on the buyer payment instrument statement

Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers

The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor here>"

Default: "AMZ*<SELLER_NAME> pay.amazon.com"
Max length: 16 characters/bytes
creationTimestamp

Type: dateTime
UTC date and time when the refund was created in ISO 8601 format
statusDetails

Type: statusDetails
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: statusDetails

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 rejected the refund. You should 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

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 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

Response

Returns HTTP 201 status response code if the operation was successful. Subsequent retry attempts using the same Idempotency Key may return a HTTP 200 status response code 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",
     "statusDetails": {
         "state": "RefundInitiated",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "releaseEnvironment": "Sandbox"
}

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

Request parameters

Name
Location
Description
refundId
(required)

Type: string
Path Parameter
Refund identifier

Response

Returns HTTP 200 status response code 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",
     "statusDetails": {
         "state": "Refunded",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "releaseEnvironment": "Sandbox"
}

Error codes

Generic errors can be found here.