Adyen Amount API

openapi: 3.2.0
info:
  version: '71'
  x-publicVersion: true
  title: Adyen Checkout Amount API
  description: This is the description of your API.
  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://checkout-test.adyen.com/v71
tags:
- name: Amount
paths:
  /payments/{paymentPspReference}/amountUpdates:
    post:
      tags:
      - Amount
      summary: Adyen Update an Authorised Amount
      description: 'Increases or decreases the authorised payment amount and returns a unique reference for this request. You get the outcome of the request asynchronously, in an **AUTHORISATION_ADJUSTMENT** webhook.


        You can only update authorised amounts that have not yet been captured.


        The amount you specify in the request is the updated amount, which is larger or smaller than the initial authorised amount.


        For more information, refer to Authorisation adjustment.'
      operationId: post-payments-paymentPspReference-amountUpdates
      x-sortIndex: 6
      x-methodName: updateAuthorisedAmount
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              amount-update:
                $ref: '#/components/examples/post-payments-paymentPspReference-amountUpdates-amount-update'
            schema:
              $ref: '#/components/schemas/PaymentAmountUpdateRequest'
      parameters:
      - description: The [`pspReference`](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/post/payments__resParam_pspReference) of the payment.
        name: paymentPspReference
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Idempotency-Key'
      responses:
        '201':
          content:
            application/json:
              examples:
                amount-update:
                  $ref: '#/components/examples/post-payments-paymentPspReference-amountUpdates-amount-update-201'
              schema:
                $ref: '#/components/schemas/PaymentAmountUpdateResponse'
          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:
  headers:
    Idempotency-Key:
      description: The idempotency key used for processing the request. Present if the key was provided in the request.
      schema:
        type: string
  schemas:
    PaymentAmountUpdateRequest:
      properties:
        amount:
          description: The updated amount. The `currency` must match the currency used in authorisation.
          $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'
        industryUsage:
          x-addedInVersion: '70'
          description: "The reason for the amount update. Possible values: \n* **delayedCharge** \n* **noShow** \n* **installment**"
          enum:
          - delayedCharge
          - installment
          - noShow
          type: string
        lineItems:
          x-addedInVersion: '70'
          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
        reference:
          description: 'Your reference for the amount update 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
      required:
      - merchantAccount
      - amount
      type: object
    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
    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
    PaymentAmountUpdateResponse:
      properties:
        amount:
          description: The updated amount.
          $ref: '#/components/schemas/Amount'
        industryUsage:
          x-addedInVersion: '70'
          description: "The reason for the amount update. Possible values: \n* **delayedCharge** \n* **noShow** \n* **installment**"
          enum:
          - delayedCharge
          - installment
          - noShow
          type: string
        lineItems:
          x-addedInVersion: '71'
          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 update. '
          type: string
        pspReference:
          description: Adyen's 16-character reference associated with the amount update request.
          type: string
        reference:
          description: 'Your reference for the amount update 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
        status:
          description: The status of your request. This will always have the value **received**.
          enum:
          - received
          type: string
      required:
      - status
      - merchantAccount
      - amount
      - reference
      - pspReference
      - paymentPspReference
      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
    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
    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
    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
    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
    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
    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
  examples:
    generic-422:
      summary: Response code 422. Unprocessable entity.
      value:
        status: 422
        errorCode: '14_030'
        message: Return URL is missing.
        errorType: validation
        pspReference: '8816118280275544'
    generic-400:
      summary: Response code 400. Bad request.
      value:
        status: 400
        errorCode: '702'
        message: 'Unexpected input: ", expected: }'
        errorType: validation
    generic-401:
      summary: Response code 401. Unauthorized.
      value:
        status: 401
        errorCode: '000'
        message: HTTP Status Response - Unauthorized
        errorType: security
    generic-500:
      summary: Response code 500. Internal server error.
      value:
        status: 500
        errorCode: '905'
        message: Payment details are not supported
        errorType: configuration
        pspReference: '8516091485743033'
    generic-403:
      summary: Response code 403. Forbidden.
      value:
        status: 403
        errorCode: '901'
        message: Invalid Merchant Account
        errorType: security
        pspReference: 881611827877203B
    post-payments-paymentPspReference-amountUpdates-amount-update-201:
      summary: Amount update requested
      description: Example response when an amount update was requested
      value:
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        paymentPspReference: 993617894903480A
        reference: YOUR_UNIQUE_REFERENCE
        pspReference: 993617894906488A
        status: received
        amount:
          currency: EUR
          value: 2500
    post-payments-paymentPspReference-amountUpdates-amount-update:
      summary: Update the amount of an authorised payment
      description: Example request to update the amount of a payment
      value:
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        amount:
          currency: EUR
          value: 2500
        reference: YOUR_UNIQUE_REFERENCE
  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
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http