adyen-openapi/yaml/BalancePlatformAccountingNotification-v1.yaml

openapi: 3.1.0
info:
  version: '1'
  x-publicVersion: true
  title: Accounting notifications
  description: 'Adyen sends notifications through webhooks to inform your system about
    incoming and outgoing transfers in your platform.


    You can use these webhooks to build your implementation. For example, you can
    use this information to update balances in your own dashboards or to keep track
    of incoming funds.'
  x-timestamp: '2022-11-24T11:24:01Z'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://www.adyen.help/hc/en-us/community/topics
    email: developer-experience@adyen.com
x-groups:
- General
tags: []
x-staticResponse: response.json
webhooks:
  balancePlatform.transfer.created:
    post:
      tags:
      - General
      summary: Transfer created
      description: Adyen sends this webhook when there are fund movements on your
        platform.
      x-addedInVersion: '1'
      operationId: post-balancePlatform.transfer.created
      x-groupName: General
      x-sortIndex: 0
      x-methodName: transferCreated
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              balancePlatform-transfer-created:
                $ref: '#/components/examples/post-balancePlatform.transfer.created-balancePlatform-transfer-created'
            schema:
              $ref: '#/components/schemas/TransferNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                balancePlatform-transfer-created:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/BalancePlatformNotificationResponse'
          description: OK - the request has succeeded.
  balancePlatform.transfer.updated:
    post:
      tags:
      - General
      summary: Transfer updated
      description: "Adyen sends this webhook when the status of a transfer changes.\
        \ Use the `data.id` to track the original transfer resource in the [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/accounting-webhooks/1/post/balancePlatform.transfer.created)\
        \ webhook.\n\nThe `status` field indicates the event that triggered the webhook.\
        \ \n\n"
      x-addedInVersion: '1'
      operationId: post-balancePlatform.transfer.updated
      x-groupName: General
      x-sortIndex: 0
      x-methodName: transferUpdated
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              balancePlatform-transfer-updated:
                $ref: '#/components/examples/post-balancePlatform.transfer.updated-balancePlatform-transfer-updated'
            schema:
              $ref: '#/components/schemas/TransferNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                balancePlatform-transfer-updated:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/BalancePlatformNotificationResponse'
          description: OK - the request has succeeded.
components:
  schemas:
    Address:
      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
    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
    BalancePlatformNotificationResponse:
      properties:
        notificationResponse:
          description: Respond with **HTTP 200 OK** and `[accepted]` in the response
            body to [accept the webhook](https://docs.adyen.com/development-resources/webhooks#accept-notifications).
          type: string
    Bank:
      properties:
        priority:
          x-addedInVersion: '1'
          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. If you don''t
            provide this in the request, Adyen sets the optimal priority.


            Possible values:


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


            * **fast**: Faster way to transfer funds but has higher fees. Recommended
            for high-priority, low-value transactions.


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


            * **instant**: Instant way to transfer funds in [SEPA countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).'
          enum:
          - fast
          - instant
          - regular
          - wire
          type: string
    BankAccountInfo:
      properties:
        address:
          description: The address of the bank account owner.
          $ref: '#/components/schemas/Address'
        iban:
          description: The international bank account number as defined in the [ISO-13616](https://www.iso.org/standard/81090.html)
            standard.
          type: string
        ownerName:
          description: The name of the bank account owner.
          $ref: '#/components/schemas/Name'
    Counterparty:
      properties:
        balanceAccountId:
          description: Unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
          type: string
        bankAccount:
          description: Contains information about the bank account.
          $ref: '#/components/schemas/BankAccountInfo'
        merchant:
          description: Contains information about the merchant.
          $ref: '#/components/schemas/MerchantData'
        transferInstrumentId:
          description: Unique identifier of the [transfer instrument](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/transferInstruments__resParam_id).
          type: string
    MerchantData:
      properties:
        mcc:
          description: The merchant category code.
          type: string
        merchantId:
          description: The merchant identifier.
          type: string
        nameLocation:
          description: Contains the merchant's name and location.
          $ref: '#/components/schemas/NameLocation'
        postalCode:
          description: The merchant postal code.
          type: string
    Name:
      properties:
        firstName:
          description: The first name.
          type: string
        fullName:
          description: The full name.
          type: string
        infix:
          description: The infix in the name, if any.
          type: string
        lastName:
          description: The last name.
          type: string
    NameLocation:
      properties:
        city:
          description: The city where the merchant is located.
          type: string
        country:
          description: The country where the merchant is located in [three-letter
            country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.
          type: string
        countryOfOrigin:
          description: The home country in [three-digit country code](https://en.wikipedia.org/wiki/ISO_3166-1_numeric)
            format, used for government-controlled merchants such as embassies.
          type: string
        name:
          description: The name of the merchant's shop or service.
          type: string
        rawData:
          description: The raw data.
          type: string
        state:
          description: The state where the merchant is located.
          type: string
    Resource:
      properties:
        balancePlatform:
          description: Unique identifier of the balance platform.
          type: string
        creationDate:
          description: 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
    Transfer:
      properties:
        amount:
          x-addedInVersion: '1'
          description: The amount of the transfer.
          $ref: '#/components/schemas/Amount'
        balanceAccountId:
          description: Unique identifier of the source [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
          type: string
        bank:
          x-addedInVersion: '1'
          description: Contains settings for bank transfers. If you are transferring
            funds to bank accounts and you don't provide this object, Adyen applies
            default settings.
          $ref: '#/components/schemas/Bank'
        counterparty:
          description: The other party in the transfer.
          $ref: '#/components/schemas/Counterparty'
        description:
          x-addedInVersion: '1'
          description: A human-readable description for the transfer. You can use
            alphanumeric characters and hyphens. We recommend sending a maximum of
            140 characters, otherwise the description may be truncated.
          type: string
        id:
          description: The ID of the resource.
          type: string
        paymentInstrumentId:
          description: Unique identifier of the source [payment instrument](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/paymentInstruments__resParam_id).
          type: string
      required:
      - amount
      - counterparty
    TransferNotificationRequest:
      properties:
        data:
          description: Contains details about the event.
          $ref: '#/components/schemas/Transfer'
        environment:
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
          type: string
        type:
          description: The type of the notification.
          enum:
          - balancePlatform.transfer.created
          - balancePlatform.transfer.updated
          type: string
      required:
      - environment
      - data
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
  examples:
    WebhookAck:
      summary: Acknowledge Webhook
      value:
        notificationResponse: '[accepted]'
    post-balancePlatform.transfer.created-balancePlatform-transfer-created:
      summary: Incoming transfer
      description: Example webhook for an incoming transfer
      value:
        data:
          accountHolder:
            description: AH description
            id: AH00000000000000000000001
            reference: AH reference
          amount:
            currency: EUR
            value: 9999
          balanceAccount:
            id: BA00000000000000000000001
          balanceAccountId: BA00000000000000000000001
          balancePlatform: YOUR_BALANCE_PLATFORM
          category: platformPayment
          creationDate: '2022-08-15T13:30:05+02:00'
          description: this_is_description
          direction: incoming
          events:
          - bookingDate: '2022-08-15T13:30:18+02:00'
            mutations: []
            status: received
          id: 3JY1Y65VWIRGUETT
          modificationMerchantReference: <auto>
          modificationPspReference: '8026605630053940'
          paymentMerchantReference: Payment reference
          pspPaymentReference: CWBC43ZX2VTFWR82
          reason: approved
          reference: this_is_reference
          sequenceNumber: 1
          status: received
          type: capture
        environment: test
        type: balancePlatform.transfer.created
    post-balancePlatform.transfer.updated-balancePlatform-transfer-updated:
      summary: Incoming transfer status changed
      description: Example webhook when an incoming transfer's status changes
      value:
        data:
          accountHolder:
            description: AH description
            id: AH00000000000000000000001
            reference: AH reference
          amount:
            currency: EUR
            value: 9999
          balanceAccount:
            id: BA00000000000000000000001
          balanceAccountId: BA00000000000000000000001
          balancePlatform: YOUR_BALANCE_PLATFORM
          balances:
          - currency: EUR
            reserved: 9999
          category: platformPayment
          creationDate: '2022-08-15T13:30:05+02:00'
          description: this_is_description
          direction: incoming
          events:
          - bookingDate: '2022-08-15T13:30:18+02:00'
            mutations: []
            status: received
          - bookingDate: '2022-08-15T13:30:18+02:00'
            mutations:
            - currency: EUR
              reserved: 9999
            status: authorised
          id: 3JY1Y65VWIRGUETT
          modificationMerchantReference: <auto>
          modificationPspReference: '8026605630053940'
          paymentMerchantReference: Payment reference
          pspPaymentReference: CWBC43ZX2VTFWR82
          reason: approved
          reference: this_is_reference
          sequenceNumber: 2
          status: authorised
          type: capture
        environment: test
        type: balancePlatform.incomingTransfer.updated