openapi: 3.1.0
info:
  version: '4'
  x-publicVersion: true
  title: Transaction webhooks
  description: 'After a transfer is booked in a balance account, Adyen sends webhooks
    with information about the transaction.


    You can use the data from these webhooks to, for example:

    - Update balances in your dashboards.

    - Keep track of incoming and outgoing funds.'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
tags:
- name: General
webhooks:
  balancePlatform.transaction.created:
    post:
      tags:
      - General
      summary: Transaction created
      description: 'After a transfer is booked in a balance account, Adyen sends this
        webhook with information about the transaction.


        '
      x-addedInVersion: '1'
      operationId: post-balancePlatform.transaction.created
      x-sortIndex: 0
      x-methodName: transactionCreated
      security:
      - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              01.balancePlatform-transaction-created-payout-ti:
                $ref: '#/components/examples/post-balancePlatform.transaction.created-01.balancePlatform-transaction-created-payout-ti'
              02.balancePlatform-transaction-created-internal-incoming:
                $ref: '#/components/examples/post-balancePlatform.transaction.created-02.balancePlatform-transaction-created-internal-incoming'
              03.balancePlatform-transaction-created-outgoing-business-account:
                $ref: '#/components/examples/post-balancePlatform.transaction.created-03.balancePlatform-transaction-created-outgoing-business-account'
            schema:
              $ref: '#/components/schemas/TransactionNotificationRequestV4'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancePlatformNotificationResponse'
          description: OK - the request has succeeded.
components:
  schemas:
    Amount:
      additionalProperties: false
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#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#minor-units).
          format: int64
          type: integer
      required:
      - value
      - currency
      type: object
    BalancePlatformNotificationResponse:
      additionalProperties: false
      properties:
        notificationResponse:
          description: Respond with any **2xx** HTTP status code to [accept the webhook](https://docs.adyen.com/development-resources/webhooks#accept-notifications).
          type: string
      type: object
    BankCategoryData:
      additionalProperties: false
      properties:
        priority:
          x-addedInVersion: '4'
          description: 'The priority for the bank transfer. This sets the speed at
            which the transfer is sent and the fees that you have to pay. Required
            for transfers with `category` **bank**.


            Possible values:


            * **regular**: for normal, low-value transactions.


            * **fast**: a faster way to transfer funds, but the fees are higher. Recommended
            for high-priority, low-value transactions.


            * **wire**: the fastest way to transfer funds, but this has the highest
            fees. Recommended for high-priority, high-value transactions.


            * **instant**: for instant funds transfers in [SEPA countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).


            * **crossBorder**: for high-value transfers to a recipient in a different
            country.


            * **internal**: for transfers to an Adyen-issued business bank account
            (by bank account number/IBAN).'
          enum:
          - crossBorder
          - fast
          - instant
          - internal
          - regular
          - wire
          type: string
        type:
          default: bank
          description: '**bank**'
          enum:
          - bank
          type: string
      type: object
    InternalCategoryData:
      additionalProperties: false
      properties:
        modificationMerchantReference:
          x-addedInVersion: '4'
          description: The capture's merchant reference included in the transfer.
          type: string
        modificationPspReference:
          x-addedInVersion: '4'
          description: The capture reference included in the transfer.
          type: string
        type:
          default: internal
          description: '**internal**'
          enum:
          - internal
          type: string
      type: object
    IssuedCard:
      additionalProperties: false
      properties:
        authorisationType:
          x-addedInVersion: '4'
          description: The authorisation type. For example, **defaultAuthorisation**,
            **preAuthorisation**, **finalAuthorisation**
          type: string
        panEntryMode:
          x-addedInVersion: '4'
          description: 'Indicates the method used for entering the PAN to initiate
            a transaction.


            Possible values: **manual**, **chip**, **magstripe**, **contactless**,
            **cof**, **ecommerce**, **token**.'
          enum:
          - chip
          - cof
          - contactless
          - ecommerce
          - magstripe
          - manual
          - token
          type: string
        processingType:
          x-addedInVersion: '4'
          description: Contains information about how the payment was processed. For
            example, **ecommerce** for online or **pos** for in-person payments.
          enum:
          - atmWithdraw
          - balanceInquiry
          - ecommerce
          - moto
          - pos
          - purchaseWithCashback
          - recurring
          - token
          type: string
        relayedAuthorisationData:
          x-addedInVersion: '4'
          description: If you are using relayed authorisation, this object contains
            information from the relayed authorisation response from your server.
          $ref: '#/components/schemas/RelayedAuthorisationData'
        schemeTraceId:
          x-addedInVersion: '4'
          description: The identifier of the original payment. This ID is provided
            by the scheme and can be alphanumeric or numeric, depending on the scheme.
            The `schemeTraceID` should refer to an original `schemeUniqueTransactionID`
            provided in an earlier payment (not necessarily processed by Adyen). A
            `schemeTraceId` is typically available for authorization adjustments or
            recurring payments.
          type: string
        schemeUniqueTransactionId:
          x-addedInVersion: '4'
          description: The unique identifier created by the scheme. This ID can be
            alphanumeric or numeric depending on the scheme.
          type: string
        type:
          default: issuedCard
          description: '**issuedCard**'
          enum:
          - issuedCard
          type: string
        validationFacts:
          x-addedInVersion: '4'
          description: The evaluation of the validation facts. See [validation checks](https://docs.adyen.com/issuing/validation-checks)
            for more information.
          items:
            $ref: '#/components/schemas/TransferNotificationValidationFact'
          type: array
      type: object
    PaymentInstrument:
      additionalProperties: false
      properties:
        description:
          description: The description of the resource.
          type: string
        id:
          description: The unique identifier of the resource.
          type: string
        reference:
          description: The reference for the resource.
          type: string
        tokenType:
          x-addedInVersion: '3'
          description: The type of wallet that the network token is associated with.
          type: string
      type: object
    PlatformPayment:
      additionalProperties: false
      properties:
        modificationMerchantReference:
          x-addedInVersion: '4'
          description: The capture's merchant reference included in the transfer.
          type: string
        modificationPspReference:
          x-addedInVersion: '4'
          description: The capture reference included in the transfer.
          type: string
        paymentMerchantReference:
          x-addedInVersion: '4'
          description: The payment's merchant reference included in the transfer.
          type: string
        platformPaymentType:
          x-addedInVersion: '4'
          description: 'Specifies the nature of the transfer. This parameter helps
            categorize transfers so you can reconcile transactions at a later time,
            using the Balance Platform Accounting Report for [marketplaces](https://docs.adyen.com/marketplaces/reports-and-fees/balance-platform-accounting-report/)
            or [platforms](https://docs.adyen.com/platforms/reports-and-fees/balance-platform-accounting-report/).


            Possible values:


            * **AcquiringFees**: for the acquiring fee incurred on a transaction.


            * **AdyenCommission**: for the transaction fee due to Adyen under [blended
            rates](https://www.adyen.com/knowledge-hub/guides/payments-training-guide/get-the-best-from-your-card-processing).


            * **AdyenFees**: for all the transaction fees due to Adyen. This is the
            sum of Adyen''s commission and Adyen''s markup.


            * **AdyenMarkup**: for the transaction fee due to Adyen under [Interchange++
            pricing](https://www.adyen.com/pricing).


            * **BalanceAccount**: or the sale amount of a transaction.


            * **Commission**: for your platform''s commission on a transaction.


            * **DCCPlatformCommission**: for the DCC Commission for the platform on
            a transaction.


            * **Interchange**: for the interchange fee (fee paid to the issuer) incurred
            on a transaction.


            * **PaymentFee**: for all of the transaction fees.


            * **Remainder**: for the left over amount after currency conversion.


            * **SchemeFee**: for the scheme fee incurred on a transaction. This is
            the sum of the interchange fees and the acquiring fees.


            * **Surcharge**: for the surcharge paid by the customer on a transaction.


            * **Tip**: for the tip paid by the customer.


            * **TopUp**: for an incoming transfer to top up your user''s balance account.


            * **VAT**: for the Value Added Tax.'
          enum:
          - AcquiringFees
          - AdyenCommission
          - AdyenFees
          - AdyenMarkup
          - BalanceAccount
          - Commission
          - DCCPlatformCommission
          - Default
          - Interchange
          - PaymentFee
          - Remainder
          - SchemeFee
          - Surcharge
          - Tip
          - TopUp
          - VAT
          type: string
        pspPaymentReference:
          x-addedInVersion: '4'
          description: The payment reference included in the transfer.
          type: string
        type:
          default: platformPayment
          description: '**platformPayment**'
          enum:
          - platformPayment
          type: string
      type: object
    RelayedAuthorisationData:
      additionalProperties: false
      properties:
        metadata:
          x-addedInVersion: '3'
          additionalProperties:
            type: string
          description: Contains key-value pairs of your references and descriptions,
            for example, `customId`:`your-own-custom-field-12345`.
          type: object
        reference:
          x-addedInVersion: '3'
          description: Your reference for the relayed authorisation data.
          type: string
      type: object
    Resource:
      additionalProperties: false
      properties:
        balancePlatform:
          description: The unique identifier of the balance platform.
          type: string
        creationDate:
          description: The date and time when the event was triggered, in ISO 8601
            extended format. For example, **2020-12-18T10:15:30+01:00**.
          format: date-time
          type: string
        id:
          description: The ID of the resource.
          type: string
      type: object
    ResourceReference:
      additionalProperties: false
      properties:
        description:
          description: The description of the resource.
          type: string
        id:
          description: The unique identifier of the resource.
          type: string
        reference:
          description: The reference for the resource.
          type: string
      type: object
    Transaction:
      additionalProperties: false
      properties:
        accountHolder:
          x-addedInVersion: '4'
          description: Contains information about the account holder associated with
            the `balanceAccount`.
          $ref: '#/components/schemas/ResourceReference'
        amount:
          x-addedInVersion: '1'
          description: Contains information about the amount of the transaction.
          $ref: '#/components/schemas/Amount'
        balanceAccount:
          x-addedInVersion: '4'
          description: Contains information about the balance account involved in
            the transaction.
          $ref: '#/components/schemas/ResourceReference'
        balancePlatform:
          x-addedInVersion: '1'
          description: The unique identifier of the balance platform.
          type: string
        bookingDate:
          x-addedInVersion: '1'
          description: The date the transaction was booked into the balance account.
          format: date-time
          type: string
        creationDate:
          description: The date and time when the event was triggered, in ISO 8601
            extended format. For example, **2020-12-18T10:15:30+01:00**.
          format: date-time
          type: string
        description:
          x-addedInVersion: '1'
          description: The `description` from the `/transfers` request.
          type: string
        id:
          x-addedInVersion: '1'
          description: The unique identifier of the transaction.
          type: string
        paymentInstrument:
          x-addedInVersion: '4'
          description: Contains information about the payment instrument that was
            used for the transaction.
          $ref: '#/components/schemas/PaymentInstrument'
        referenceForBeneficiary:
          x-addedInVersion: '1'
          description: "The reference sent to or received from the counterparty.\n\
            \n* For outgoing funds, this is the [`referenceForBeneficiary`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__resParam_referenceForBeneficiary)\
            \ from the  [`/transfers`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__reqParam_referenceForBeneficiary)\
            \ request.\n\n * For incoming funds, this is the reference from the sender."
          type: string
        status:
          x-addedInVersion: '1'
          description: "The status of the transaction.\n\n Possible values:\n\n* **pending**:\
            \ The transaction is still pending.\n\n* **booked**: The transaction has\
            \ been booked to the balance account.\n\n"
          enum:
          - booked
          - pending
          type: string
        transfer:
          x-addedInVersion: '4'
          description: Contains information about the transfer related to the transaction.
          $ref: '#/components/schemas/TransferView'
        valueDate:
          x-addedInVersion: '1'
          description: The date the transfer amount becomes available in the balance
            account.
          format: date-time
          type: string
      required:
      - id
      - accountHolder
      - balanceAccount
      - amount
      - status
      - bookingDate
      - valueDate
      - balancePlatform
      type: object
    TransactionNotificationRequestV4:
      additionalProperties: false
      properties:
        data:
          description: Contains details about the event.
          $ref: '#/components/schemas/Transaction'
        environment:
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
          type: string
        timestamp:
          description: When the event was queued.
          format: date-time
          type: string
        type:
          description: Type of the webhook.
          enum:
          - balancePlatform.transaction.created
          type: string
      required:
      - environment
      - data
      type: object
    TransferNotificationValidationFact:
      additionalProperties: false
      properties:
        result:
          description: The evaluation result of the validation fact.
          type: string
        type:
          description: The type of the validation fact.
          type: string
      type: object
    TransferView:
      additionalProperties: false
      properties:
        categoryData:
          x-addedInVersion: '4'
          description: The relevant data according to the transfer category.
          oneOf:
          - $ref: '#/components/schemas/BankCategoryData'
          - $ref: '#/components/schemas/InternalCategoryData'
          - $ref: '#/components/schemas/IssuedCard'
          - $ref: '#/components/schemas/PlatformPayment'
        id:
          description: The ID of the resource.
          type: string
        reference:
          x-addedInVersion: '4'
          description: The [`reference`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__reqParam_reference)
            from the `/transfers` request. If you haven't provided any, Adyen generates
            a unique reference.
          type: string
      required:
      - reference
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
  examples:
    post-balancePlatform.transaction.created-01.balancePlatform-transaction-created-payout-ti:
      summary: Transaction related to a payout
      description: Example webhook for a transaction related to a payout to a transfer
        instrument
      value:
        data:
          id: EVJN00000000000000000000000003EUR
          amount:
            value: -10000
            currency: EUR
          status: booked
          transfer:
            categoryData:
              priority: regular
              type: bank
            id: 3JNC3O5ZVFLLGV4B
            reference: ' Your internal reference for the transfer'
          valueDate: '2023-08-11T16:19:35+02:00'
          bookingDate: '2023-08-11T16:31:02+02:00'
          creationDate: '2023-08-11T16:19:35+02:00'
          description: Your description of the transfer
          referenceForBeneficiary: Your reference sent to the beneficiary of the transfer
          accountHolder:
            id: AH00000000000000000000001
            reference: Your reference for the account holder
            description: Your description of the account holder
          balanceAccount:
            id: BA00000000000000000000001
            description: Your description of the balance account from where the amount
              is debited.
          balancePlatform: YOUR_BALANCE_PLATFORM
        environment: test
        timestamp: '2023-08-11T16:16:35+02:00'
        type: balancePlatform.transaction.created
    post-balancePlatform.transaction.created-02.balancePlatform-transaction-created-internal-incoming:
      summary: Transaction related to an incoming internal transfer
      description: Example webhook for a transaction related to an incoming internal
        transfer
      value:
        data:
          id: EVJN00000000000000000000000003EUR
          amount:
            value: 10000
            currency: EUR
          status: booked
          transfer:
            categoryData:
              type: internal
            id: 48TYZO5ZVURJ2FCW
            reference: ' Your internal reference for the transfer'
          valueDate: '2023-08-11T16:19:35+02:00'
          bookingDate: '2023-08-11T16:31:02+02:00'
          creationDate: '2023-08-11T16:19:35+02:00'
          description: The sender's of the transfer
          referenceForBeneficiary: The sender's reference sent to the beneficiary
            of the transfer
          accountHolder:
            id: AH00000000000000000000001
            reference: Your reference for the account holder
            description: Your description of the account holder
          balanceAccount:
            id: BA00000000000000000000001
            description: Your description of the balance account from where the amount
              is debited.
          balancePlatform: YOUR_BALANCE_PLATFORM
        environment: test
        timestamp: '2023-08-11T16:16:35+02:00'
        type: balancePlatform.transaction.created
    post-balancePlatform.transaction.created-03.balancePlatform-transaction-created-outgoing-business-account:
      summary: Transaction related to an outgoing bank transfer
      description: Example webhook for a transaction related to an outgoing bank transfer
      value:
        data:
          id: EVJN00000000000000000000000003EUR
          amount:
            value: -10000
            currency: EUR
          status: booked
          transfer:
            categoryData:
              priority: regular
              type: bank
            id: 3JNC3O5ZVFLLGV4B
            reference: ' Your internal reference for the transfer'
          valueDate: '2023-08-11T16:19:35+02:00'
          bookingDate: '2023-08-11T16:31:02+02:00'
          creationDate: '2023-08-11T16:19:35+02:00'
          description: Your description of the transfer
          referenceForBeneficiary: Your reference sent to the beneficiary of the transfer
          accountHolder:
            id: AH00000000000000000000001
            reference: Your reference for the account holder
            description: Your description of the account holder
          balanceAccount:
            id: BA00000000000000000000001
            description: Your description of the balance account from where the amount
              is debited.
          paymentInstrument:
            id: PI00000000000000000000001
            description: Your description of the payment instrument
          balancePlatform: YOUR_BALANCE_PLATFORM
        environment: test
        timestamp: '2023-08-11T16:16:35+02:00'
        type: balancePlatform.transaction.created