adyen-openapi/yaml/NotificationConfigurationService-v5.yaml

openapi: 3.0.0
servers:
  - url: 'https://cal-test.adyen.com/cal/services/Notification/v5'
info:
  version: '5'
  title: Adyen MarketPay Notification Configuration API
  description: |-
    The MarketPay Notification Configuration API provides endpoints for configuration a subscription to a marketplace's MarketPay-related notifications. Notifications are sent upon the occurrence of certain events (such as a KYC check completion or a payout completion), and the subscription to these notifications dictates to where they are sent.

    For further information on MarketPay notifications, please visit the [MarketPay documentation](https://docs.adyen.com/marketpay).
    ## Authentication
    To connect to the MarketPay API, you must use basic authentication credentials of your web service user. If you don't have one, please contact the [Adyen Support Team](https://support.adyen.com/hc/en-us/requests/new). Then use its credentials to authenticate your request, for example:

    ```
    curl
    -U "ws@MarketPlace.YourMarketPlace":"YourWsPassword" \
    -H "Content-Type: application/json" \
    ...
    ```
    Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).

    ## Versioning
    MarketPay API supports versioning of its endpoints through a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number.

    For example:
    ```
    https://cal-test.adyen.com/cal/services/Notification/v5/createNotificationConfiguration
    ```
  termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
  contact:
    name: Adyen Support
    url: 'https://support.adyen.com/'
    email: support@adyen.com
x-groups:
  - General
paths:
  /createNotificationConfiguration:
    post:
      summary: Configure a new subscription to notifications.
      description: 'This endpoint is used to create a subscription to MarketPay event notifications. After the subscription is created, the events specified in the configuration will be sent to the URL specified in the configuration. Subscriptions must be configured on a per-event basis (as opposed to, for example, a per-account holder basis), so all event notifications of a marketplace and of a given type will be sent to the same endpoint(s). A marketplace may have multiple endpoints if desired; an event notification may be sent to as many or as few different endpoints as configured.'
      x-groupName: General
      x-sortIndex: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNotificationConfigurationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNotificationConfigurationResponse'
          description: OK - the request has succeeded.
  /deleteNotificationConfigurations:
    post:
      summary: Delete an existing notification subscription configuration.
      description: 'This endpoint is used to delete an existing notification subscription configuration. After the subscription is deleted, no further event notifications will be sent to the URL that was in the subscription.'
      x-groupName: General
      x-sortIndex: 6
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteNotificationConfigurationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
          description: OK - the request has succeeded.
  /getNotificationConfiguration:
    post:
      summary: Retrieve an existing notification subscription configuration.
      description: This endpoint is used to retrieve the details of the configuration of a notification subscription.
      x-groupName: General
      x-sortIndex: 2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetNotificationConfigurationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNotificationConfigurationResponse'
          description: OK - the request has succeeded.
  /getNotificationConfigurationList:
    post:
      summary: Retrieve a list of existing notification subscription configurations.
      description: This endpoint is used to retrieve the details of the configurations of all of the notification subscriptions in the marketplace of the executing user.
      x-groupName: General
      x-sortIndex: 3
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNotificationConfigurationListResponse'
          description: OK - the request has succeeded.
  /testNotificationConfiguration:
    post:
      summary: Test an existing notification configuration.
      description: 'This endpoint is used to test an existing notification subscription configuration. For each event type specified, a test notification will be generated and sent to the URL configured in the subscription specified.'
      x-groupName: General
      x-sortIndex: 4
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestNotificationConfigurationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestNotificationConfigurationResponse'
          description: OK - the request has succeeded.
  /updateNotificationConfiguration:
    post:
      summary: Update an existing notification subscription configuration.
      description: 'This endpoint is used to update an existing notification subscription configuration. If updating the event types, all event types desired must be provided, otherwise the previous event type configuration will be overwritten.'
      x-groupName: General
      x-sortIndex: 5
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationConfigurationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNotificationConfigurationResponse'
          description: OK - the request has succeeded.
components:
  schemas:
    CreateNotificationConfigurationRequest:
      properties:
        configurationDetails:
          description: Details of the prospective notification subscription configuration.
          $ref: '#/components/schemas/NotificationConfigurationDetails'
      required:
        - configurationDetails
    DeleteNotificationConfigurationRequest:
      properties:
        notificationIds:
          description: A list of IDs of the notification subscription configurations to be deleted.
          items:
            format: int64
            type: integer
          type: array
      required:
        - notificationIds
    EmptyRequest: {}
    ErrorFieldType:
      properties:
        errorCode:
          description: The validation error code.
          format: int32
          type: integer
        errorDescription:
          description: A description of the validation error.
          type: string
        fieldType:
          description: The type of error field.
          $ref: '#/components/schemas/FieldType'
    ExchangeMessage:
      properties:
        messageCode:
          type: string
        messageDescription:
          type: string
    FieldType:
      properties:
        field:
          description: The full name of the property.
          type: string
        fieldName:
          description: The type of the field.
          enum:
            - accountCode
            - accountHolderCode
            - accountHolderDetails
            - accountNumber
            - accountStateType
            - accountStatus
            - accountType
            - address
            - bankAccount
            - bankAccountCode
            - bankAccountName
            - bankAccountUUID
            - bankBicSwift
            - bankCity
            - bankCode
            - bankName
            - bankStatement
            - branchCode
            - businessContact
            - cardToken
            - checkCode
            - city
            - companyRegistration
            - country
            - countryCode
            - currency
            - currencyCode
            - dateOfBirth
            - description
            - destinationAccountCode
            - document
            - documentExpirationDate
            - documentIssuerCountry
            - documentIssuerState
            - documentName
            - documentNumber
            - documentType
            - doingBusinessAs
            - drivingLicence
            - drivingLicenceBack
            - drivingLicense
            - email
            - firstName
            - fullPhoneNumber
            - gender
            - hopWebserviceUser
            - houseNumberOrName
            - iban
            - idCard
            - idCardBack
            - idCardFront
            - idNumber
            - identityDocument
            - individualDetails
            - lastName
            - legalBusinessName
            - legalEntity
            - legalEntityType
            - merchantAccount
            - merchantCategoryCode
            - merchantReference
            - microDeposit
            - name
            - nationality
            - originalReference
            - ownerCity
            - ownerCountryCode
            - ownerHouseNumberOrName
            - ownerName
            - ownerPostalCode
            - ownerState
            - ownerStreet
            - passport
            - passportNumber
            - payoutMethodCode
            - personalData
            - phoneCountryCode
            - phoneNumber
            - postalCode
            - primaryCurrency
            - reason
            - registrationNumber
            - returnUrl
            - schedule
            - shareholder
            - shareholderCode
            - socialSecurityNumber
            - sourceAccountCode
            - stateOrProvince
            - status
            - store
            - storeDetail
            - storeName
            - storeReference
            - street
            - taxId
            - tier
            - tierNumber
            - transferCode
            - unknown
            - value
            - virtualAccount
            - visaNumber
            - webAddress
          type: string
        shareholderCode:
          description: 'The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.'
          type: string
    GenericResponse:
      properties:
        invalidFields:
          description: Contains field validation errors that would prevent requests from being processed.
          items:
            $ref: '#/components/schemas/ErrorFieldType'
          type: array
        pspReference:
          description: The reference of a request.  Can be used to uniquely identify the request.
          type: string
        resultCode:
          description: The result code.
          type: string
      required:
        - pspReference
    GetNotificationConfigurationListResponse:
      properties:
        configurations:
          description: Details of the notification subscription configurations.
          items:
            $ref: '#/components/schemas/NotificationConfigurationDetails'
          type: array
        invalidFields:
          description: Contains field validation errors that would prevent requests from being processed.
          items:
            $ref: '#/components/schemas/ErrorFieldType'
          type: array
        pspReference:
          description: The reference of a request.  Can be used to uniquely identify the request.
          type: string
        resultCode:
          description: The result code.
          type: string
      required:
        - pspReference
        - configurations
    GetNotificationConfigurationRequest:
      properties:
        notificationId:
          description: The ID of the notification subscription configuration whose details are to be retrieved.
          format: int64
          type: integer
      required:
        - notificationId
    GetNotificationConfigurationResponse:
      properties:
        configurationDetails:
          description: Details of the notification subscription configuration.
          $ref: '#/components/schemas/NotificationConfigurationDetails'
        invalidFields:
          description: Contains field validation errors that would prevent requests from being processed.
          items:
            $ref: '#/components/schemas/ErrorFieldType'
          type: array
        pspReference:
          description: The reference of a request.  Can be used to uniquely identify the request.
          type: string
        resultCode:
          description: The result code.
          type: string
      required:
        - pspReference
        - configurationDetails
    NotificationConfigurationDetails:
      properties:
        active:
          description: Indicates whether the notification subscription is active.
          type: boolean
        apiVersion:
          description: The API version of the notification to send.
          format: int32
          type: integer
        description:
          description: |-
            A description of the notification subscription configuration.
            >Required when creating a configuration, forbidden when updating a configuration.
          type: string
        eventConfigs:
          description: The types of events whose notifications apply to this configuration.
          items:
            $ref: '#/components/schemas/NotificationEventConfiguration'
          type: array
        hmacSignatureKey:
          description: |-
            A string with which to salt the notification(s) before hashing. If this field is provided, a hash value will be included under the notification header `HmacSignature` and the hash protocol will be included under the notification header `Protocol`. A notification body along with its `hmacSignatureKey` and `Protocol` can be used to calculate a hash value; matching this hash value with the `HmacSignature` will ensure that the notification body has not been tampered with or corrupted.

            >Must be a 32-byte hex-encoded string (i.e. a string containing 64 hexadecimal characters; e.g. "b0ea55c2fe60d4d1d605e9c385e0e7f7e6cafbb939ce07010f31a327a0871f27").

            The omission of this field will preclude the provision of the `HmacSignature` and `Protocol` headers in notification(s).
          type: string
        notificationId:
          description: |-
            The ID of the configuration.
            >Required if updating an existing configuration, ignored during the creation of a configuration.
          format: int64
          type: integer
        notifyPassword:
          description: The password to use when accessing the notifyURL with the specified username.
          type: string
        notifyURL:
          description: The URL to which the notifications are to be sent.
          type: string
        notifyUsername:
          description: The username to use when accessing the notifyURL.
          type: string
        sslProtocol:
          description: |-
            The SSL protocol employed by the endpoint.
            >Permitted values: `SSL`, `SSLInsecureCiphers`, `TLS`, `TLSv10`, `TLSv10InsecureCiphers`, `TLSv11`, `TLSv12`.
          enum:
            - SSL
            - SSLInsecureCiphers
            - TLS
            - TLSv10
            - TLSv10InsecureCiphers
            - TLSv11
            - TLSv12
          type: string
      required:
        - eventConfigs
        - notifyURL
    NotificationEventConfiguration:
      properties:
        eventType:
          description: |-
            The type of event triggering the notification.
            >Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`, `ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_STORE_STATUS_CHANGE`, `ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`, `PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`, `BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`.
          enum:
            - ACCOUNT_CLOSED
            - ACCOUNT_CREATED
            - ACCOUNT_HOLDER_CREATED
            - ACCOUNT_HOLDER_LIMIT_REACHED
            - ACCOUNT_HOLDER_PAYOUT
            - ACCOUNT_HOLDER_STATUS_CHANGE
            - ACCOUNT_HOLDER_STORE_STATUS_CHANGE
            - ACCOUNT_HOLDER_UPCOMING_DEADLINE
            - ACCOUNT_HOLDER_UPDATED
            - ACCOUNT_HOLDER_VERIFICATION
            - ACCOUNT_UPDATED
            - BENEFICIARY_SETUP
            - COMPENSATE_NEGATIVE_BALANCE
            - DIRECT_DEBIT_INITIATED
            - PAYMENT_FAILURE
            - REPORT_AVAILABLE
            - SCHEDULED_REFUNDS
            - TRANSFER_FUNDS
            - TRANSFER_FUNDS_REFUND
          type: string
        includeMode:
          description: |-
            Indicates whether the specified eventType is to be sent to the endpoint or all events other than the specified eventType (and other specified eventTypes) are to be sent.
            >Permitted values: `INCLUDE`, `EXCLUDE`.
            >- `INCLUDE`: send the specified eventType.
            >- `EXCLUDE`: send all eventTypes other than the specified eventType (and other eventTypes marked with `EXCLUDE`).
          enum:
            - EXCLUDE
            - INCLUDE
          type: string
      required:
        - eventType
        - includeMode
    TestNotificationConfigurationRequest:
      properties:
        eventTypes:
          description: |-
            The event types to test.  If left blank, then all of the configured event types will be tested.
            >Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`, `ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_STORE_STATUS_CHANGE` `ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`, `PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`, `BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`.
          items:
            enum:
              - ACCOUNT_CLOSED
              - ACCOUNT_CREATED
              - ACCOUNT_HOLDER_CREATED
              - ACCOUNT_HOLDER_LIMIT_REACHED
              - ACCOUNT_HOLDER_PAYOUT
              - ACCOUNT_HOLDER_STATUS_CHANGE
              - ACCOUNT_HOLDER_STORE_STATUS_CHANGE
              - ACCOUNT_HOLDER_UPCOMING_DEADLINE
              - ACCOUNT_HOLDER_UPDATED
              - ACCOUNT_HOLDER_VERIFICATION
              - ACCOUNT_UPDATED
              - BENEFICIARY_SETUP
              - COMPENSATE_NEGATIVE_BALANCE
              - DIRECT_DEBIT_INITIATED
              - PAYMENT_FAILURE
              - REPORT_AVAILABLE
              - SCHEDULED_REFUNDS
              - TRANSFER_FUNDS
              - TRANSFER_FUNDS_REFUND
            type: string
          type: array
        notificationId:
          description: The ID of the notification subscription configuration to be tested.
          format: int64
          type: integer
      required:
        - notificationId
    TestNotificationConfigurationResponse:
      properties:
        errorMessages:
          description: Any error messages encountered.
          items:
            type: string
          type: array
        eventTypes:
          description: |-
            The event types that were tested.
            >Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`, `ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_STORE_STATUS_CHANGE` `ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`, `PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`, `BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`.
          items:
            enum:
              - ACCOUNT_CLOSED
              - ACCOUNT_CREATED
              - ACCOUNT_HOLDER_CREATED
              - ACCOUNT_HOLDER_LIMIT_REACHED
              - ACCOUNT_HOLDER_PAYOUT
              - ACCOUNT_HOLDER_STATUS_CHANGE
              - ACCOUNT_HOLDER_STORE_STATUS_CHANGE
              - ACCOUNT_HOLDER_UPCOMING_DEADLINE
              - ACCOUNT_HOLDER_UPDATED
              - ACCOUNT_HOLDER_VERIFICATION
              - ACCOUNT_UPDATED
              - BENEFICIARY_SETUP
              - COMPENSATE_NEGATIVE_BALANCE
              - DIRECT_DEBIT_INITIATED
              - PAYMENT_FAILURE
              - REPORT_AVAILABLE
              - SCHEDULED_REFUNDS
              - TRANSFER_FUNDS
              - TRANSFER_FUNDS_REFUND
            type: string
          type: array
        exchangeMessages:
          description: The notification message and related response messages.
          items:
            $ref: '#/components/schemas/ExchangeMessage'
          type: array
        invalidFields:
          description: Contains field validation errors that would prevent requests from being processed.
          items:
            $ref: '#/components/schemas/ErrorFieldType'
          type: array
        notificationId:
          description: The ID of the notification subscription configuration.
          format: int64
          type: integer
        okMessages:
          description: A list of messages describing the testing steps.
          items:
            type: string
          type: array
        pspReference:
          description: The reference of a request.  Can be used to uniquely identify the request.
          type: string
        resultCode:
          description: The result code.
          type: string
      required:
        - pspReference
        - notificationId
        - eventTypes
        - okMessages
        - exchangeMessages
    UpdateNotificationConfigurationRequest:
      properties:
        configurationDetails:
          description: Details of the notification subscription configuration to be updated.
          $ref: '#/components/schemas/NotificationConfigurationDetails'
      required:
        - configurationDetails