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