openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute Captures 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: Captures
paths:
/payments/{paymentPspReference}/captures:
post:
tags:
- Captures
summary: Adyen Capture an Authorised Payment
description: " Captures an authorised payment and returns a unique reference for this request. You get the outcome of the request asynchronously, in a [**CAPTURE** webhook](https://docs.adyen.com/online-payments/capture#capture-notification).\n\nYou can capture either the full authorised amount or a part of the authorised amount. By default, any unclaimed amount after a partial capture gets cancelled. This does not apply if you enabled multiple partial captures on your account and the payment method supports multiple partial captures. \n\n[Automatic capture](https://docs.adyen.com/online-payments/capture#automatic-capture) is the default setting for most payment methods. In these cases, you don't need to make capture requests. However, making capture requests for payments that are captured automatically does not result in double charges.\n\nFor more information, refer to [Capture](https://docs.adyen.com/online-payments/capture)."
operationId: post-payments-paymentPspReference-captures
x-sortIndex: 1
x-methodName: captureAuthorisedPayment
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
capture:
$ref: '#/components/examples/post-payments-paymentPspReference-captures-capture'
schema:
$ref: '#/components/schemas/PaymentCaptureRequest'
parameters:
- description: The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment that you want to capture.
name: paymentPspReference
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/Idempotency-Key'
responses:
'201':
content:
application/json:
examples:
capture:
$ref: '#/components/examples/post-payments-paymentPspReference-captures-capture-201'
schema:
$ref: '#/components/schemas/PaymentCaptureResponse'
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
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
PaymentCaptureResponse:
properties:
amount:
description: The captured 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
paymentPspReference:
description: 'The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment to capture. '
type: string
platformChargebackLogic:
x-addedInVersion: '70'
description: Defines how to book chargebacks when using [Adyen for Platforms](https://docs.adyen.com/marketplaces-and-platforms/processing-payments#chargebacks-and-disputes).
$ref: '#/components/schemas/PlatformChargebackLogic'
pspReference:
description: Adyen's 16-character reference associated with the capture request.
type: string
reference:
description: Your reference for the capture 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
subMerchants:
x-addedInVersion: '70'
description: List of sub-merchants.
items:
$ref: '#/components/schemas/SubMerchantInfo'
type: array
required:
- status
- merchantAccount
- amount
- pspReference
- paymentPspReference
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
SubMerchantInfo:
properties:
address:
$ref: '#/components/schemas/BillingAddress'
id:
type: string
mcc:
type: string
name:
type: string
taxId:
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
PaymentCaptureRequest:
properties:
amount:
description: The amount that you want to capture. 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
platformChargebackLogic:
x-addedInVersion: '70'
description: Defines how to book chargebacks when using [Adyen for Platforms](https://docs.adyen.com/marketplaces-and-platforms/processing-payments#chargebacks-and-disputes).
$ref: '#/components/schemas/PlatformChargebackLogic'
reference:
description: 'Your reference for the capture 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
subMerchants:
x-addedInVersion: '70'
description: A List of sub-merchants.
items:
$ref: '#/components/schemas/SubMerchantInfo'
type: array
required:
- merchantAccount
- amount
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
PlatformChargebackLogic:
properties:
behavior:
x-addedInVersion: '68'
description: 'The method of handling the chargeback.
Possible values: **deductFromLiableAccount**, **deductFromOneBalanceAccount**, **deductAccordingToSplitRatio**.'
enum:
- deductAccordingToSplitRatio
- deductFromLiableAccount
- deductFromOneBalanceAccount
type: string
costAllocationAccount:
x-addedInVersion: '68'
description: The unique identifier of the balance account to which the chargeback fees are booked. By default, the chargeback fees are booked to your liable balance account.
type: string
targetAccount:
x-addedInVersion: '68'
description: 'The unique identifier of the balance account against which the disputed amount is booked.
Required if `behavior` is **deductFromOneBalanceAccount**.'
type: string
type: object
BillingAddress:
properties:
city:
description: 'The name of the city. Maximum length: 3000 characters.'
maxLength: 3000
type: string
country:
description: 'The two-character ISO-3166-1 alpha-2 country code. For example, **US**.
> If you don''t know the country or are not collecting the country from the shopper, provide `country` as `ZZ`.'
type: string
houseNumberOrName:
description: 'The number or name of the house. Maximum length: 3000 characters.'
maxLength: 3000
type: string
postalCode:
description: A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
type: string
stateOrProvince:
description: 'The two-character ISO 3166-2 state or province code. For example, **CA** in the US or **ON** in Canada.
> Required for the US and Canada.'
type: string
street:
description: 'The name of the street. Maximum length: 3000 characters.
> The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.'
maxLength: 3000
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
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-captures-capture:
summary: Capture an authorised payment
description: Example capture request
value:
reference: YOUR_UNIQUE_REFERENCE
merchantAccount: YOUR_MERCHANT_ACCOUNT
amount:
value: 2000
currency: EUR
platformChargebackLogic:
behavior: deductFromOneBalanceAccount
targetAccount: BA00000000000000000000001
costAllocationAccount: BA00000000000000000000001
generic-403:
summary: Response code 403. Forbidden.
value:
status: 403
errorCode: '901'
message: Invalid Merchant Account
errorType: security
pspReference: 881611827877203B
post-payments-paymentPspReference-captures-capture-201:
summary: Capture requested
description: Example response when a capture was requested
value:
merchantAccount: YOUR_MERCHANT_ACCOUNT
paymentPspReference: 993617894903480A
reference: YOUR_UNIQUE_REFERENCE
pspReference: 993617894906488A
status: received
amount:
value: 2000
currency: EUR
platformChargebackLogic:
behavior: deductFromOneBalanceAccount
targetAccount: BA00000000000000000000001
costAllocationAccount: BA00000000000000000000001
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