Refund a captured payment

post/payments/{paymentPspReference}/refunds

Refunds a payment that has been captured, and returns a unique reference for this request. You get the outcome of the request asynchronously, in a REFUND webhook.

You can refund either the full captured amount or a part of the captured amount. You can also perform multiple partial refunds, as long as their sum doesn't exceed the captured amount.

Some payment methods do not support partial refunds. To learn if a payment method supports partial refunds, refer to the payment method page such as cards, iDEAL, or Klarna.

If you want to refund a payment but are not sure whether it has been captured, use the /payments/{paymentPspReference}/reversals endpoint instead.

For more information, refer to Refund.

Endpoint destination URL

https://checkout-test.adyen.com/v70/payments/{paymentPspReference}/refunds

Header Parameters

Required

Optional

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Path Parameters

Required

Optional

The pspReference of the payment that you want to refund.

Request Parameters

Required

Optional

The amount that you want to refund. The currency must match the currency used in authorisation, the value must be smaller than or equal to the authorised amount.

Information about your application. For more details, see Building Adyen solutions.

This is only available for PayPal refunds. The pspReference of the specific capture to refund.

Enhanced scheme data that may be required for processing the payment. For example, airline information.

Airline enhanced scheme data that may be required for processing the transaction and/or for interchange savings.

The amount charged for boarding the plane, in minor units.

Encoding: Numeric
minLength: 1 character
maxLength: 11 characters
additionalData key: airline.boarding_fee

The IATA 3-digit accounting code (PAX) that identifies the carrier.

Format: IATA 3-digit accounting code (PAX)
Example: KLM = 074
minLength: 3 characters
maxLength: 3 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.airline_code

The CRS used to make the reservation and purchase the ticket.

Encoding: ASCII
minLength: 4 characters
maxLength: 4 characters
additionalData key: airline.computerized_reservation_system

The alphanumeric customer reference number.

Encoding: ASCII
maxLength: 20 characters
If you send more than 20 characters, the customer reference number is truncated
Must not start with a space or be all spaces.
additionalData key: airline.customer_reference_number

The IATA 2-letter accounting code (PAX) that identifies the carrier.

Encoding: ASCII
Example: KLM = KL
minLength: 2 characters
maxLength: 2 characters
Must not start with a space or be all spaces.
additionalData key: airline.airline_designator_code

A code that identifies the type of item bought. The description of the code can appear on credit card statements.

Encoding: ASCII
Example: Passenger ticket = 01
minLength: 2 characters
maxLength: 2 characters
additionalData key: airline.document_type

The flight departure date. Time is optional.

Format for date only: yyyy-MM-dd
Format for date and time: yyyy-MM-ddTHH:mm
Use local time of departure airport.
minLength: 10 characters
maxLength: 16 characters
additionalData key: airline.flight_date

The IATA 2-letter accounting code (PAX) that identifies the carrier. This field is required if the airline data includes leg details.

Example: KLM = KL
minLength: 2 characters
maxLength: 2 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.leg[N].carrier_code

A one-letter travel class identifier. The following are common:

F: first class
J: business class
Y: economy class
W: premium economy
Encoding: ASCII
minLength: 1 character
maxLength: 1 character
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.leg[N].class_of_travel

Date and time of travel in format yyyy-MM-ddTHH:mm.

Use local time of departure airport.
minLength: 16 characters
maxLength: 16 characters
additionalData key: airline.leg[N].date_of_travel

The IATA three-letter airport code of the departure airport. This field is required if the airline data includes leg details.

Encoding: ASCII
Example: Amsterdam = AMS
minLength: 3 characters
maxLength: 3 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.leg[N].depart_airport

The amount of departure tax charged, in minor units.

Encoding: Numeric
minLength: 1
maxLength: 11
Must not be all zeros.
additionalData key: airline.leg[N].depart_tax

The IATA 3-letter airport code of the destination airport. This field is required if the airline data includes leg details.

Example: Amsterdam = AMS
Encoding: ASCII
minLength: 3 characters
maxLength: 3 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.leg[N].destination_code

The fare basis code, alphanumeric.

minLength: 1 character
maxLength: 15 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.leg[N].fare_base_code

The flight identifier.

minLength: 1 character
maxLength: 5 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.leg[N].flight_number

A one-letter code that indicates whether the passenger is entitled to make a stopover. Can be a space, O if the passenger is entitled to make a stopover, or X if they are not.

Encoding: ASCII
minLength: 1 character
maxLength: 1 character
additionalData key: airline.leg[N].stop_over_code

The passenger's name, initials, and title.

Format: last name + first name or initials + title
Example: FLYER / MARY MS
minLength: 1 character
maxLength: 20 characters
If you send more than 20 characters, the name is truncated
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: airline.passenger_name

Car rental enhanced scheme data that may be required for processing the transaction and/or for interchange savings.

The customer service phone number of the car rental company.

Format: Alphanumeric
maxLength: 17
For US and CA numbers must be 10 characters in length
Must not contain any special characters such as + or -
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: carRental.customerServiceTollFreeNumber

Indicates if the customer didn't pick up their rental car.

additionalData key: carRental.noShowIndicator

Indicates whether the rental rate is daily or weekly.

additionalData key: carRental.rateIndicator

The rental agreement number for the car rental.

Format: ASCII
maxLength: 9 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: carRental.rentalAgreementNumber

The classification of the rental car.

Format: Alphanumeric
maxLength: 4 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: carRental.rentalClassId

The number of days the car is rented for.

Format: Numeric
Max value: 9999
additionalData key: carRental.daysRented

Rental rate, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
Frequency of the rental rate is specified in the rateType field.
additionalData key: carRental.rate

The name of the person renting the car.

Format: ASCII
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: carRental.renterName

Indicates if the goods or services were tax-exempt, or if tax was not collected.

additionalData key: carRental.taxExemptIndicator

Level 2 and Level 3 enhanced scheme data that may be required for processing the transaction and/or for interchange savings.

The reference number to identify the customer and their order.

Format: ASCII
Max length: 25 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: enhancedSchemeData.customerReference

The destination address information.

The duty tax amount, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: enhancedSchemeData.dutyAmount

The shipping amount, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: enhancedSchemeData.freightAmount

The list of item detail lines.

The code that identifies the item in a standardized commodity coding scheme. There are different commodity coding schemes:

UNSPSC commodity codes
HS commodity codes
NAICS commodity codes
NAPCS commodity codes
Encoding: ASCII
Max length: 12 characters
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: enhancedSchemeData.itemDetailLine[N].commodityCode

A description of the item, that provides details about the purchase.

For Visa transactions with level 3 ESD, the description must not be the same or very similar to your merchant name, or, consist only of common words like "product", or "service".

Encoding: ASCII
Max length: 26 characters
Must not be a single character.
Must not be blank.
Must not be all special characters.
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: enhancedSchemeData.itemDetailLine[N].description

The discount amount, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: enhancedSchemeData.itemDetailLine[N].discountAmount

The product code. Must be a unique product code associated with the item or service. This can be your unique code for the item, or the manufacturer's product code.

Encoding: ASCII.
Max length: 12 characters
additionalData key: enhancedSchemeData.itemDetailLine[N].productCode

The number of items. Must be an integer greater than zero.

Encoding: Numeric
Max value: 9999
additionalData key: enhancedSchemeData.itemDetailLine[N].quantity

The total amount for the line item, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000

See Amount requirements for level 2/3 ESD to learn more about how to calculate the line item total.

additionalData key: enhancedSchemeData.itemDetailLine[N].totalAmount

The unit of measurement for an item.

Encoding: ASCII
Max length: 3 characters
additionalData key: enhancedSchemeData.itemDetailLine[N].unitOfMeasure

The unit price, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: enhancedSchemeData.itemDetailLine[N].unitPrice

The date of the order.

Min Length: 10 characters
Max Length: 10 characters
Format ISO 8601: yyyy-MM-dd
additionalData key: enhancedSchemeData.orderDate

The postal code of the address where the item is shipped from.

Encoding: ASCII
Max length: 10 characters
For the US, it must be in five or nine digits format. For example, 10001 or 10001-0000.
For Canada, it must be in 6 digits format. For example, M4B 1G5.
additionalData key: enhancedSchemeData.shipFromPostalCode

The amount of state or provincial tax included in the total transaction amount, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
For L2 data: must not be all zeroes.
For L3 data: can be zero.
additionalData key: enhancedSchemeData.totalTaxAmount

Lodging enhanced scheme data that may be required for processing the transaction and/or for interchange savings.

The check-in date.

Min Length: 10 characters
Max Length: 10 characters
Format ISO 8601: yyyy-MM-dd
additionalData key: lodging.checkInDate

The check-out date.

Min Length: 10 characters
Max Length: 10 characters
Format ISO 8601: yyyy-MM-dd
additionalData key: lodging.checkOutDate

The toll-free phone number for the lodging customer service.

Format: Alphanumeric
For US and CA numbers must be 10 characters in length
Must not start with a space
Must not contain any special characters such as + or -
Must not be all zeros.
additionalData key: lodging.customerServiceTollFreeNumber

Indicates that the facility complies with the Hotel and Motel Fire Safety Act of 1990.

additionalData key: lodging.fireSafetyActIndicator

The folio information for the booking.

Any charges for food and beverages associated with the booking, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: lodging.foodBeverageCharges

The category of lodging charges for the payment.

additionalData key: lodging.specialProgramCode

Indicates if the customer didn't check in for their booking.

additionalData key: lodging.noShowIndicator

The prepaid expenses for the booking, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: lodging.prepaidExpenses

The lodging property location's phone number.

Format: Alphanumeric
Min length: 10 characters
For US and CA numbers must be 10 characters in length
Must not start with a space
Must not contain any special characters such as + or -
Must not be all zeros.
additionalData key: lodging.propertyPhoneNumber

The name of the person renting the room.

Format: ASCII
Must not start with a space or be all spaces.
Must not be all zeros.
additionalData key: lodging.renterName

The list of rooms booked.

The total room tax amount, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: lodging.totalRoomTax

The total tax amount, in minor units.

For example, 2000 means USD 20.00.
Encoding: Numeric
Max value: 10000000000
additionalData key: lodging.totalTax

Temporary services enhanced scheme data that may be required for processing the transaction and/or for interchange savings.

Price and product information of the refunded items, required for partial refunds.

This field is required for partial refunds with 3x 4x Oney, Affirm, Afterpay, Atome, Clearpay, Klarna, Ratepay, Walley, and Zip.

The merchant account that is used to process the payment.

The reason for the refund request.

Possible values:

FRAUD
CUSTOMER REQUEST
RETURN
DUPLICATE
OTHER

Your reference for the refund request. Maximum length: 80 characters.

An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms. For more information, see how to process payments for marketplaces or platforms.

The unique identifier of the account to which the split amount is booked. Required if type is MarketPlace or BalanceAccount.

Classic Platforms integration: The accountCode of the account to which the split amount is booked.
Balance Platform: The balanceAccountId of the account to which the split amount is booked.

The amount of the split item.

Required for all split types in the Classic Platforms integration.
Required if type is BalanceAccount, Commission, Surcharge, Default, or VAT in your Balance Platform integration.

Your description for the split item.

Your unique reference for the part of the payment booked to the specified account.

This is required if type is MarketPlace (Classic Platforms integration) or BalanceAccount (Balance Platform).

For the other types, we also recommend providing a unique reference so you can reconcile the split and the associated payment in the transaction overview and in the reports.

The part of the payment you want to book to the specified account.

Possible values for the Balance Platform:

BalanceAccount: Books part of the payment (specified in amount) to the specified account.
Transaction fees types that you can book to the specified account:
- AcquiringFees: The aggregated amount of the interchange and scheme fees.
- PaymentFee: The aggregated amount of all transaction fees.
- AdyenFees: The aggregated amount of Adyen's commission and markup fees.
- AdyenCommission: The transaction fees due to Adyen under blended rates.
- AdyenMarkup: The transaction fees due to Adyen under Interchange ++ pricing.
- Interchange: The fees paid to the issuer for each payment made with the card network.
- SchemeFee: The fees paid to the card scheme for using their network.
Commission: Your platform's commission on the payment (specified in amount), booked to your liable balance account.
Remainder: The amount left over after a currency conversion, booked to the specified account.
Surcharge: The payment acceptance fee imposed by the card scheme or debit network provider, paid by your user's customer.
TopUp: Allows you and your users to top up balance accounts using direct debit, card payments, or other payment methods.
VAT: The value-added tax charged on the payment, booked to your platforms liable balance account.
Default: In very specific use cases, allows you to book the specified amount to the specified account. For more information, contact Adyen support.

Possible values for the Classic Platforms integration: Commission, Default, MarketPlace, PaymentFee, VAT.

The online store or physical store that is processing the refund. This must be the same as the store name configured in your Customer Area. Otherwise, you get an error and the refund fails.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

201 - Created
The request has been fulfilled and has resulted in one or more new resources being created.
amountobject
The refund amount.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code of the amount.
valueinteger
The numeric value of the amount, in minor units.
capturePspReferencestring
This is only available for PayPal refunds. The pspReference of the specific capture to refund.
lineItemsarray[object]
Price and product information of the refunded items, required for partial refunds.

This field is required for partial refunds with 3x 4x Oney, Affirm, Afterpay, Atome, Clearpay, Klarna, Ratepay, Walley, and Zip.

amountExcludingTaxinteger
Item amount excluding the tax, in minor units.
amountIncludingTaxinteger
Item amount including the tax, in minor units.
brandstring
Brand of the item.
colorstring
Color of the item.
descriptionstring
Max length: 10000
Description of the line item.
idstring
ID of the line item.
imageUrlstring
Link to the picture of the purchased item.
itemCategorystring
Item category, used by the payment methods PayPal and Ratepay.
manufacturerstring
Manufacturer of the item.
marketplaceSellerIdstring
Marketplace seller id.
productUrlstring
Link to the purchased item.
quantityinteger
Number of items.
receiverEmailstring
Email associated with the given product in the basket (usually in electronic gift cards).
sizestring
Size of the item.
skustring
Stock keeping unit.
taxAmountinteger
Tax amount, in minor units.
taxPercentageinteger
Tax percentage, represented as a basis point integer. For example:

530 for 5.3% (five point three percent)

2100 for 21% (twenty-one percent)

upcstring
Universal Product Code.
merchantAccountstring
The merchant account that is used to process the payment.
merchantRefundReasonstring
Your reason for the refund request.
paymentPspReferencestring
The pspReference of the payment to refund.
pspReferencestring
Adyen's 16-character reference associated with the refund request.
referencestring
Your reference for the refund request.
splitsarray[object]
An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms. For more information, see how to process payments for marketplaces or platforms.
accountstring
The unique identifier of the account to which the split amount is booked. Required if type is MarketPlace or BalanceAccount.

Classic Platforms integration: The accountCode of the account to which the split amount is booked.

Balance Platform: The balanceAccountId of the account to which the split amount is booked.

amountobject
The amount of the split item.

Required for all split types in the Classic Platforms integration.

Required if type is BalanceAccount, Commission, Surcharge, Default, or VAT in your Balance Platform integration.

currencystring
Min length: 3Max length: 3
The three-character ISO currency code. By default, this is the original payment currency.
valueinteger
The value of the split amount, in minor units.
descriptionstring
Your description for the split item.
referencestring
Your unique reference for the part of the payment booked to the specified account.

This is required if type is MarketPlace (Classic Platforms integration) or BalanceAccount (Balance Platform).

For the other types, we also recommend providing a unique reference so you can reconcile the split and the associated payment in the transaction overview and in the reports.
typestring
The part of the payment you want to book to the specified account.

Possible values for the Balance Platform:

BalanceAccount: Books part of the payment (specified in amount) to the specified account.

Transaction fees types that you can book to the specified account:

AcquiringFees: The aggregated amount of the interchange and scheme fees.

PaymentFee: The aggregated amount of all transaction fees.

AdyenFees: The aggregated amount of Adyen's commission and markup fees.

AdyenCommission: The transaction fees due to Adyen under blended rates.

AdyenMarkup: The transaction fees due to Adyen under Interchange ++ pricing.

Interchange: The fees paid to the issuer for each payment made with the card network.

SchemeFee: The fees paid to the card scheme for using their network.

Commission: Your platform's commission on the payment (specified in amount), booked to your liable balance account.

Remainder: The amount left over after a currency conversion, booked to the specified account.

Surcharge: The payment acceptance fee imposed by the card scheme or debit network provider, paid by your user's customer.

TopUp: Allows you and your users to top up balance accounts using direct debit, card payments, or other payment methods.

VAT: The value-added tax charged on the payment, booked to your platforms liable balance account.

Default: In very specific use cases, allows you to book the specified amount to the specified account. For more information, contact Adyen support.

Possible values for the Classic Platforms integration: Commission, Default, MarketPlace, PaymentFee, VAT.
statusstring
The status of your request. This will always have the value received.
storestring
The online store or physical store that is processing the refund. This must be the same as the store name configured in your Customer Area. Otherwise, you get an error and the refund fails.
400 - Bad Request
A problem reading or understanding the request.
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
401 - Unauthorized
Authentication required.
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
422 - Unprocessable Entity
A request validation error.
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
500 - Internal Server Error
The server could not process the request.
additionalDataobject
Contains additional information about the payment. Some data fields are included only if you select them first. Go to Customer Area > Developers > Additional data.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.

Refund a captured payment

HTTP Responses

201 - Created

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error