openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute Refunds API
description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
x-timestamp: '2023-05-30T15:27:20Z'
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: Refunds
paths:
/payments/{paymentPspReference}/refunds:
post:
tags:
- Refunds
summary: Adyen Refund a Captured Payment
description: "Refunds a payment that has been [captured](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/{paymentPspReference}/captures), and returns a unique reference for this request. You get the outcome of the request asynchronously, in a [**REFUND** webhook](https://docs.adyen.com/online-payments/refund#refund-webhook).\n\nYou 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.\n\n> 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](https://docs.adyen.com/payment-methods/cards#supported-cards), [iDEAL](https://docs.adyen.com/payment-methods/ideal), or [Klarna](https://docs.adyen.com/payment-methods/klarna). \n\nIf you want to refund a payment but are not sure whether it has been captured, use the [`/payments/{paymentPspReference}/reversals`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments/{paymentPspReference}/reversals) endpoint instead.\n\nFor more information, refer to [Refund](https://docs.adyen.com/online-payments/refund)."
operationId: post-payments-paymentPspReference-refunds
x-sortIndex: 4
x-methodName: refundCapturedPayment
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
refund:
$ref: '#/components/examples/post-payments-paymentPspReference-refunds-refund'
schema:
$ref: '#/components/schemas/PaymentRefundRequest'
parameters:
- description: The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment that you want to refund.
name: paymentPspReference
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/Idempotency-Key'
responses:
'201':
content:
application/json:
examples:
refund:
$ref: '#/components/examples/post-payments-paymentPspReference-refunds-refund-201'
schema:
$ref: '#/components/schemas/PaymentRefundResponse'
description: Created - the request has been fulfilled and has resulted in one or more new resources being created.
headers:
Idempotency-Key:
$ref: '#/components/headers/Idempotency-Key'
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
headers:
Idempotency-Key:
$ref: '#/components/headers/Idempotency-Key'
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
LineItem:
properties:
amountExcludingTax:
description: Item amount excluding the tax, in minor units.
format: int64
type: integer
amountIncludingTax:
description: Item amount including the tax, in minor units.
format: int64
type: integer
brand:
x-addedInVersion: '70'
description: Brand of the item.
type: string
color:
x-addedInVersion: '70'
description: Color of the item.
type: string
description:
description: Description of the line item.
type: string
id:
description: ID of the line item.
type: string
imageUrl:
description: Link to the picture of the purchased item.
type: string
itemCategory:
description: Item category, used by the payment methods PayPal and Ratepay.
type: string
manufacturer:
x-addedInVersion: '70'
description: Manufacturer of the item.
type: string
productUrl:
description: Link to the purchased item.
type: string
quantity:
description: Number of items.
format: int64
type: integer
receiverEmail:
x-addedInVersion: '70'
description: Email associated with the given product in the basket (usually in electronic gift cards).
type: string
size:
x-addedInVersion: '70'
description: Size of the item.
type: string
sku:
x-addedInVersion: '70'
description: Stock keeping unit.
type: string
taxAmount:
description: Tax amount, in minor units.
format: int64
type: integer
taxPercentage:
description: Tax percentage, in minor units.
format: int64
type: integer
upc:
x-addedInVersion: '70'
description: Universal Product Code.
type: string
type: object
PaymentRefundRequest:
properties:
amount:
description: 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.
$ref: '#/components/schemas/Amount'
applicationInfo:
description: Information about your application. For more details, see [Building Adyen solutions](https://docs.adyen.com/development-resources/building-adyen-solutions).
$ref: '#/components/schemas/ApplicationInfo'
lineItems:
description: 'Price and product information of the refunded items, required for [partial refunds](https://docs.adyen.com/online-payments/refund#refund-a-payment).
> This field is required for partial refunds with 3x 4x Oney, Affirm, Afterpay, Atome, Clearpay, Klarna, Ratepay, Walley, and Zip.'
items:
$ref: '#/components/schemas/LineItem'
type: array
merchantAccount:
description: The merchant account that is used to process the payment.
type: string
merchantRefundReason:
description: Your reason for the refund request
enum:
- FRAUD
- CUSTOMER REQUEST
- RETURN
- DUPLICATE
- OTHER
type: string
reference:
description: 'Your reference for the refund request. Maximum length: 80 characters.'
type: string
splits:
description: An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms. For details, refer to [Providing split information](https://docs.adyen.com/marketplaces-and-platforms/processing-payments#providing-split-information).
items:
$ref: '#/components/schemas/Split'
type: array
store:
description: The online store or [physical store](https://docs.adyen.com/point-of-sale/design-your-integration/determine-account-structure/#create-stores) 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.
type: string
required:
- merchantAccount
- amount
type: object
ApplicationInfo:
properties:
adyenLibrary:
description: Adyen-developed software, such as libraries and plugins, used to interact with the Adyen API. For example, Magento plugin, Java API library, etc.
$ref: '#/components/schemas/CommonField'
adyenPaymentSource:
description: Adyen-developed software to get payment details. For example, Checkout SDK, Secured Fields SDK, etc.
$ref: '#/components/schemas/CommonField'
externalPlatform:
description: Third-party developed platform used to initiate payment requests. For example, Magento, Zuora, etc.
$ref: '#/components/schemas/ExternalPlatform'
merchantApplication:
description: Merchant developed software, such as cashier application, used to interact with the Adyen API.
$ref: '#/components/schemas/CommonField'
merchantDevice:
description: Merchant device information.
$ref: '#/components/schemas/MerchantDevice'
shopperInteractionDevice:
description: Shopper interaction device, such as terminal, mobile device or web browser, to initiate payment requests.
$ref: '#/components/schemas/ShopperInteractionDevice'
type: object
CommonField:
properties:
name:
description: Name of the field. For example, Name of External Platform.
type: string
version:
description: Version of the field. For example, Version of External Platform.
type: string
type: object
MerchantDevice:
properties:
os:
description: Operating system running on the merchant device.
type: string
osVersion:
description: Version of the operating system on the merchant device.
type: string
reference:
description: Merchant device reference.
type: string
type: object
SplitAmount:
properties:
currency:
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes). By default, this is the original payment currency.
maxLength: 3
minLength: 3
type: string
value:
description: The value of the split amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
type: object
ServiceError:
properties:
additionalData:
x-addedInVersion: '46'
additionalProperties:
type: string
description: Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
type: object
errorCode:
description: The error code mapped to the error message.
type: string
errorType:
description: The category of the error.
type: string
message:
description: A short explanation of the issue.
type: string
pspReference:
description: The PSP reference of the payment.
type: string
status:
description: The HTTP response status.
format: int32
type: integer
type: object
ExternalPlatform:
properties:
integrator:
description: External platform integrator.
type: string
name:
description: Name of the field. For example, Name of External Platform.
type: string
version:
description: Version of the field. For example, Version of External Platform.
type: string
type: object
ShopperInteractionDevice:
properties:
locale:
description: Locale on the shopper interaction device.
type: string
os:
description: Operating system running on the shopper interaction device.
type: string
osVersion:
description: Version of the operating system on the shopper interaction device.
type: string
type: object
Amount:
properties:
currency:
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
maxLength: 3
minLength: 3
type: string
value:
description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
- currency
type: object
PaymentRefundResponse:
properties:
amount:
description: The refund amount.
$ref: '#/components/schemas/Amount'
lineItems:
description: 'Price and product information of the refunded items, required for [partial refunds](https://docs.adyen.com/online-payments/refund#refund-a-payment).
> This field is required for partial refunds with 3x 4x Oney, Affirm, Afterpay, Atome, Clearpay, Klarna, Ratepay, Walley, and Zip.'
items:
$ref: '#/components/schemas/LineItem'
type: array
merchantAccount:
description: The merchant account that is used to process the payment.
type: string
merchantRefundReason:
description: Your reason for the refund request.
enum:
- FRAUD
- CUSTOMER REQUEST
- RETURN
- DUPLICATE
- OTHER
type: string
paymentPspReference:
description: 'The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment to refund. '
type: string
pspReference:
description: Adyen's 16-character reference associated with the refund request.
type: string
reference:
description: Your reference for the refund request.
type: string
splits:
description: An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms. For details, refer to [Providing split information](https://docs.adyen.com/marketplaces-and-platforms/processing-payments#providing-split-information).
items:
$ref: '#/components/schemas/Split'
type: array
status:
description: The status of your request. This will always have the value **received**.
enum:
- received
type: string
store:
description: The online store or [physical store](https://docs.adyen.com/point-of-sale/design-your-integration/determine-account-structure/#create-stores) 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.
type: string
required:
- status
- merchantAccount
- amount
- pspReference
- paymentPspReference
type: object
Split:
properties:
account:
description: 'The unique identifier of the account to which the split amount is booked. Required if `type` is **MarketPlace** or **BalanceAccount**.
* [Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic): The [`accountCode`](https://docs.adyen.com/api-explorer/Account/latest/post/updateAccount#request-accountCode) of the account to which the split amount is booked.
* [Balance Platform](https://docs.adyen.com/marketplaces-and-platforms): The [`balanceAccountId`](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/balanceAccounts/_id_#path-id) of the account to which the split amount is booked.'
type: string
amount:
description: 'The amount of the split item.
* Required for all split types in the [Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic).
* Required if `type` is **BalanceAccount**, **Commission**, **Default**, or **VAT** in your [Balance Platform](https://docs.adyen.com/marketplaces-and-platforms) integration.'
$ref: '#/components/schemas/SplitAmount'
description:
description: Your description for the split item.
type: string
reference:
description: 'Your unique reference for the split item.
This is required if `type` is **MarketPlace** ([Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic)) or **BalanceAccount** ([Balance Platform](https://docs.adyen.com/marketplaces-and-platforms)).
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.'
type: string
type:
description: 'The type of the split item.
Possible values:
* [Classic Platforms integration](https://docs.adyen.com/marketplaces-and-platforms/classic): **Commission**, **Default**, **Marketplace**, **PaymentFee**, **VAT**.
* [Balance Platform](https://docs.adyen.com/marketplaces-and-platforms): **BalanceAccount**, **Commission**, **Default**, **PaymentFee**, **Remainder**, **Surcharge**, **Tip**, **VAT**.'
enum:
- AcquiringFees
- AdyenCommission
- AdyenFees
- AdyenMarkup
- BalanceAccount
- Commission
- Default
- Interchange
- MarketPlace
- PaymentFee
- Remainder
- SchemeFee
- Surcharge
- Tip
- VAT
type: string
required:
- type
type: object
examples:
generic-401:
summary: Response code 401. Unauthorized.
value:
status: 401
errorCode: '000'
message: HTTP Status Response - Unauthorized
errorType: security
generic-400:
summary: Response code 400. Bad request.
value:
status: 400
errorCode: '702'
message: 'Unexpected input: ", expected: }'
errorType: validation
generic-422:
summary: Response code 422. Unprocessable entity.
value:
status: 422
errorCode: '14_030'
message: Return URL is missing.
errorType: validation
pspReference: '8816118280275544'
generic-500:
summary: Response code 500. Internal server error.
value:
status: 500
errorCode: '905'
message: Payment details are not supported
errorType: configuration
pspReference: '8516091485743033'
post-payments-paymentPspReference-refunds-refund:
summary: Refund a payment
description: Example refund request
value:
amount:
currency: EUR
value: 2500
reference: YOUR_UNIQUE_REFERENCE
merchantAccount: YOUR_MERCHANT_ACCOUNT
post-payments-paymentPspReference-refunds-refund-201:
summary: Refund requested
description: Example response when a refund was requested
value:
merchantAccount: YOUR_MERCHANT_ACCOUNT
paymentPspReference: 993617894903480A
reference: YOUR_UNIQUE_REFERENCE
pspReference: 993617894906488A
status: received
amount:
currency: EUR
value: 2500
generic-403:
summary: Response code 403. Forbidden.
value:
status: 403
errorCode: '901'
message: Invalid Merchant Account
errorType: security
pspReference: 881611827877203B
parameters:
Idempotency-Key:
description: A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).
example: 37ca9c97-d1d1-4c62-89e8-706891a563ed
name: Idempotency-Key
in: header
schema:
type: string
headers:
Idempotency-Key:
description: The idempotency key used for processing the request. Present if the key was provided in the request.
schema:
type: string
securitySchemes:
ApiKeyAuth:
in: header
name: X-API-Key
type: apiKey
BasicAuth:
scheme: basic
type: http
x-groups:
- Account holders
- Accounts
- Verification