openapi: 3.1.0
info:
  version: '3'
  x-publicVersion: true
  title: Management Webhooks
  description: 'Adyen uses webhooks to inform your system about events that happen
    with your Adyen company and merchant accounts, stores, payment terminals, and
    payment methods when using [Management API](https://docs.adyen.com/api-explorer/#/ManagementService/latest/overview).


    When an event occurs, Adyen makes an HTTP POST request to a URL on your server
    and includes the details of the event in the request body.


    See [Webhooks](https://docs.adyen.com/development-resources/webhooks) for more
    information.'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
x-groups:
- Merchant account
- Payment method
tags:
- name: Merchant account
- name: Payment method
x-staticResponse: response.json
webhooks:
  merchant.created:
    post:
      tags:
      - Merchant account
      summary: Merchant account created
      description: A merchant account [was created](https://docs.adyen.com/api-explorer/#/ManagementService/latest/post/merchants).
      x-addedInVersion: '1'
      operationId: post-merchant.created
      x-groupName: Merchant account
      x-sortIndex: 1
      x-methodName: merchantAccountCreated
      security:
      - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              merchant.created:
                $ref: '#/components/examples/post-merchant.created-merchant.created'
            schema:
              $ref: '#/components/schemas/MerchantCreatedNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                merchant.created:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/AccountNotificationResponse'
          description: OK - the request has succeeded.
  merchant.updated:
    post:
      tags:
      - Merchant account
      summary: Merchant account capability updated
      description: There were changes to the verification status and capabilities
        of a [merchant account](https://docs.adyen.com/api-explorer/#/ManagementService/latest/post/merchants).
        If the verification fails, this webhook includes the errors and the actions
        that you can take to resolve them.
      x-addedInVersion: '1'
      operationId: post-merchant.updated
      x-groupName: Merchant account
      x-sortIndex: 2
      x-methodName: merchantAccountCapabilityUpdated
      security:
      - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              merchant-updated-valid:
                $ref: '#/components/examples/post-merchant.updated-merchant-updated-valid'
              merchant-updated-with-errors:
                $ref: '#/components/examples/post-merchant.updated-merchant-updated-with-errors'
            schema:
              $ref: '#/components/schemas/MerchantUpdatedNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                merchant-updated-valid:
                  $ref: '#/components/examples/WebhookAck'
                merchant-updated-with-errors:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/AccountNotificationResponse'
          description: OK - the request has succeeded.
  paymentMethod.created:
    post:
      tags:
      - Payment method
      summary: Payment method created
      description: A request to [add a payment method](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings)
        was completed.
      x-addedInVersion: '1'
      operationId: post-paymentMethod.created
      x-groupName: Payment method
      x-sortIndex: 1
      x-methodName: paymentMethodCreated
      security:
      - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              paymentMethod.created:
                $ref: '#/components/examples/post-paymentMethod.created-paymentMethod.created'
            schema:
              $ref: '#/components/schemas/PaymentMethodCreatedNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                paymentMethod.created:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/PaymentMethodNotificationResponse'
          description: OK - the request has succeeded.
  paymentMethod.requestRemoved:
    post:
      tags:
      - Payment method
      summary: Payment method request removed
      description: A request to add a payment method is removed. You must make another
        request to [add a payment method](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings).
      x-addedInVersion: '2'
      operationId: post-paymentMethod.requestRemoved
      x-groupName: Payment method
      x-sortIndex: 3
      x-methodName: paymentMethodRequestRemoved
      security:
      - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              paymentMethod.requestRemoved:
                $ref: '#/components/examples/post-paymentMethod.requestRemoved-paymentMethod.requestRemoved'
            schema:
              $ref: '#/components/schemas/PaymentMethodRequestRemovedNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                paymentMethod.requestRemoved:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/PaymentMethodNotificationResponse'
          description: OK - the request has succeeded.
  paymentMethod.requestScheduledForRemoval:
    post:
      tags:
      - Payment method
      summary: Payment method request scheduled for removal
      description: A request to [add a payment method](https://docs.adyen.com/api-explorer/Management/latest/post/merchants/_merchantId_/paymentMethodSettings)
        will be removed in 30 days. To make sure the payment method is added, provide
        the missing [KYC information](https://docs.adyen.com/marketplaces-and-platforms/collect-verification-details).
      x-addedInVersion: '2'
      operationId: post-paymentMethod.requestScheduledForRemoval
      x-groupName: Payment method
      x-sortIndex: 2
      x-methodName: paymentMethodRequestScheduledForRemoval
      security:
      - BasicAuth: []
      requestBody:
        content:
          application/json:
            examples:
              paymentMethod.requestScheduledForRemoval:
                $ref: '#/components/examples/post-paymentMethod.requestScheduledForRemoval-paymentMethod.requestScheduledForRemoval'
            schema:
              $ref: '#/components/schemas/PaymentMethodScheduledForRemovalNotificationRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                paymentMethod.requestScheduledForRemoval:
                  $ref: '#/components/examples/WebhookAck'
              schema:
                $ref: '#/components/schemas/PaymentMethodNotificationResponse'
          description: OK - the request has succeeded.
components:
  schemas:
    AccountCapabilityData:
      properties:
        allowed:
          description: Indicates whether the capability is allowed. Adyen sets this
            to **true** if the verification is successful.
          type: boolean
        allowedLevel:
          description: 'The allowed level of the capability. Some capabilities have
            different levels which correspond to thresholds. Higher levels may require
            additional checks and increased monitoring.Possible values: **notApplicable**,
            **low**, **medium**, **high**.'
          type: string
        capability:
          description: The name of the capability. For example, **sendToTransferInstrument**.
          type: string
        problems:
          description: List of entities that has problems with verification. The information
            includes the details of the errors and the actions that you can take to
            resolve them.
          items:
            $ref: '#/components/schemas/CapabilityProblem'
          type: array
        requested:
          description: Indicates whether you requested the capability.
          type: boolean
        requestedLevel:
          description: 'The level that you requested for the capability. Some capabilities
            have different levels which correspond to thresholds. Higher levels may
            require additional checks and increased monitoring.Possible values: **notApplicable**,
            **low**, **medium**, **high**.'
          type: string
        verificationStatus:
          description: 'The status of the verification checks for the capability.


            Possible values:


            * **pending**: Adyen is running the verification.


            * **invalid**: The verification failed. Check if the `errors` array contains
            more information.


            * **valid**: The verification was successful.


            * **rejected**: Adyen checked the information and found reasons to not
            allow the capability.

            '
          type: string
      required:
      - requestedLevel
      - requested
      type: object
    AccountCreateNotificationData:
      properties:
        capabilities:
          additionalProperties:
            $ref: '#/components/schemas/AccountCapabilityData'
          description: Key-value pairs that specify the actions that the merchant
            account can do and its settings. The key is a capability. For example,
            the **sendToTransferInstrument** is the capability required before you
            can pay out funds to the bank account. The value is an object containing
            the settings for the capability.
          type: object
        companyId:
          description: The unique identifier of the company account.
          type: string
        legalEntityId:
          description: The unique identifier of the [legal entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id).
          type: string
        merchantId:
          description: The unique identifier of the merchant account.
          type: string
        status:
          description: 'The status of the merchant account.


            Possible values:


            * **PreActive**: The merchant account has been created. Users cannot access
            the merchant account in the Customer Area. The account cannot process
            payments.

            * **Active**: Users can access the merchant account in the Customer Area.
            If the company account is also **Active**, then payment processing and
            payouts are enabled.

            * **InactiveWithModifications**: Users can access the merchant account
            in the Customer Area. The account cannot process new payments but can
            still modify payments, for example issue refunds. The account can still
            receive payouts.

            * **Inactive**: Users can access the merchant account in the Customer
            Area. Payment processing and payouts are disabled.

            * **Closed**: The account is closed and this cannot be reversed. Users
            cannot log in. Payment processing and payouts are disabled.'
          type: string
      required:
      - merchantId
      - companyId
      - status
      - capabilities
      type: object
    AccountNotificationResponse:
      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
      type: object
    AccountUpdateNotificationData:
      properties:
        capabilities:
          additionalProperties:
            $ref: '#/components/schemas/AccountCapabilityData'
          description: Key-value pairs that specify what you can do with the merchant
            account and its settings. The key is a capability. For example, the **sendToTransferInstrument**
            is the capability required before you can pay out the funds of a merchant
            account to a [bank account](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments).
            The value is an object containing the settings for the capability.
          type: object
        legalEntityId:
          description: The unique identifier of the [legal entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id).
          type: string
        merchantId:
          description: The unique identifier of the merchant account.
          type: string
        status:
          description: 'The status of the merchant account.


            Possible values:


            * **PreActive**: The merchant account has been created. Users cannot access
            the merchant account in the Customer Area. The account cannot process
            payments.

            * **Active**: Users can access the merchant account in the Customer Area.
            If the company account is also **Active**, then payment processing and
            payouts are enabled.

            * **InactiveWithModifications**: Users can access the merchant account
            in the Customer Area. The account cannot process new payments but can
            still modify payments, for example issue refunds. The account can still
            receive payouts.

            * **Inactive**: Users can access the merchant account in the Customer
            Area. Payment processing and payouts are disabled.

            * **Closed**: The account is closed and this cannot be reversed. Users
            cannot log in. Payment processing and payouts are disabled.'
          type: string
      required:
      - merchantId
      - status
      - capabilities
      type: object
    CapabilityProblem:
      properties:
        entity:
          description: The ID and the type of entity that has verification errors.
          $ref: '#/components/schemas/CapabilityProblemEntity'
        verificationErrors:
          description: List of verification errors.
          items:
            $ref: '#/components/schemas/VerificationError'
          type: array
      type: object
    CapabilityProblemEntity:
      properties:
        documents:
          description: List of document IDs to which the verification errors related
            to the capabilities correspond to.
          items:
            type: string
          type: array
        id:
          description: The ID of the entity.
          type: string
        owner:
          description: The owner of the entity that has an error. For example, if
            the `entity.type` is **BankAccount**, then the `owner` contains the details
            of the legal entity that owns the bank account.
          $ref: '#/components/schemas/CapabilityProblemEntity-recursive'
        type:
          description: 'The type of entity.


            Possible values: **LegalEntity**, **BankAccount**, or **Document**.'
          enum:
          - BankAccount
          - Document
          - LegalEntity
          type: string
      type: object
    CapabilityProblemEntity-recursive:
      properties:
        documents:
          description: List of document IDs to which the verification errors related
            to the capabilities correspond to.
          items:
            type: string
          type: array
        id:
          description: The ID of the entity.
          type: string
        type:
          description: 'The type of entity.


            Possible values: **LegalEntity**, **BankAccount**, or **Document**.'
          enum:
          - BankAccount
          - Document
          - LegalEntity
          type: string
      required: []
      type: object
    MerchantCreatedNotificationRequest:
      properties:
        createdAt:
          description: Timestamp for when the webhook was created.
          format: date-time
          type: string
        data:
          description: Contains event details.
          $ref: '#/components/schemas/AccountCreateNotificationData'
        environment:
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
          type: string
        type:
          description: Type of notification.
          enum:
          - merchant.created
          type: string
      required:
      - environment
      - createdAt
      - data
      - type
      type: object
    MerchantUpdatedNotificationRequest:
      properties:
        createdAt:
          description: Timestamp for when the webhook was created.
          format: date-time
          type: string
        data:
          description: Contains event details.
          $ref: '#/components/schemas/AccountUpdateNotificationData'
        environment:
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
          type: string
        type:
          description: Type of notification.
          enum:
          - merchant.updated
          type: string
      required:
      - environment
      - createdAt
      - data
      - type
      type: object
    MidServiceNotificationData:
      properties:
        allowed:
          description: Indicates whether receiving payments is allowed. This value
            is set to **true** by Adyen after screening your merchant account.
          type: boolean
        enabled:
          description: Indicates whether the payment method is enabled (**true**)
            or disabled (**false**).
          type: boolean
        id:
          description: The unique identifier of the resource.
          type: string
        merchantId:
          description: The unique identifier of the merchant account.
          type: string
        reference:
          description: Your reference for the payment method.
          type: string
        status:
          x-addedInVersion: '2'
          description: 'The status of the request to add a payment method. Possible
            values:


            * **success**: the payment method was added.

            * **failure**: the request failed.

            * **capabilityPending**: the **receivePayments** capability is not allowed.

            '
          enum:
          - success
          - failure
          - capabilityPending
          - dataRequired
          - updatesExpected
          type: string
        storeId:
          description: The unique identifier of the [store](https://docs.adyen.com/api-explorer/#/ManagementService/latest/post/merchants/{id}/paymentMethodSettings__reqParam_storeId),
            if any.
          type: string
        type:
          description: Payment method [variant](https://docs.adyen.com/development-resources/paymentmethodvariant#management-api).
          type: string
        verificationStatus:
          description: 'Payment method status. Possible values:

            * **valid**

            * **pending**

            * **invalid**

            * **rejected**'
          enum:
          - valid
          - pending
          - invalid
          - rejected
          type: string
      required:
      - status
      - merchantId
      - id
      - type
      type: object
    PaymentMethodCreatedNotificationRequest:
      properties:
        createdAt:
          description: Timestamp for when the webhook was created.
          format: date-time
          type: string
        data:
          description: Contains event details.
          $ref: '#/components/schemas/MidServiceNotificationData'
        environment:
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
          type: string
        type:
          description: Type of notification.
          enum:
          - paymentMethod.created
          type: string
      required:
      - environment
      - createdAt
      - data
      - type
      type: object
    PaymentMethodNotificationResponse:
      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
      type: object
    PaymentMethodRequestRemovedNotificationRequest:
      properties:
        createdAt:
          description: Timestamp for when the webhook was created.
          format: date-time
          type: string
        data:
          description: Contains event details.
          $ref: '#/components/schemas/MidServiceNotificationData'
        environment:
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
          type: string
        type:
          description: Type of notification.
          enum:
          - paymentMethod.requestRemoved
          type: string
      required:
      - environment
      - createdAt
      - data
      - type
      type: object
    PaymentMethodScheduledForRemovalNotificationRequest:
      properties:
        createdAt:
          description: Timestamp for when the webhook was created.
          format: date-time
          type: string
        data:
          description: Contains event details.
          $ref: '#/components/schemas/MidServiceNotificationData'
        environment:
          description: 'The environment from which the webhook originated.


            Possible values: **test**, **live**.'
          type: string
        type:
          description: Type of notification.
          enum:
          - paymentMethod.requestScheduledForRemoval
          type: string
      required:
      - environment
      - createdAt
      - data
      - type
      type: object
    RemediatingAction:
      properties:
        code:
          description: The remediating action code.
          type: string
        message:
          description: A description of how you can resolve the verification error.
          type: string
      type: object
    VerificationError:
      properties:
        code:
          description: The verification error code.
          type: string
        message:
          description: The verification error message.
          type: string
        remediatingActions:
          description: The actions that you can take to resolve the verification error.
          items:
            $ref: '#/components/schemas/RemediatingAction'
          type: array
        subErrors:
          description: More granular information about the verification error.
          items:
            $ref: '#/components/schemas/VerificationError-recursive'
          type: array
        type:
          description: 'The type of verification error.


            Possible values: **invalidInput**, **dataMissing**, and **pendingStatus**.'
          enum:
          - dataMissing
          - invalidInput
          - pendingStatus
          type: string
      type: object
    VerificationError-recursive:
      properties:
        code:
          description: The verification error code.
          type: string
        message:
          description: The verification error message.
          type: string
        type:
          description: 'The type of verification error.


            Possible values: **invalidInput**, **dataMissing**, and **pendingStatus**.'
          enum:
          - dataMissing
          - invalidInput
          - pendingStatus
          type: string
        remediatingActions:
          description: The actions that you can take to resolve the verification error.
          items:
            $ref: '#/components/schemas/RemediatingAction'
          type: array
      required: []
      type: object
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
  examples:
    WebhookAck:
      summary: Acknowledge Webhook
      value:
        notificationResponse: '[accepted]'
    post-merchant.created-merchant.created:
      summary: Merchant account created
      description: Example webhook when a merchant account was created
      value:
        type: merchant.created
        environment: test
        createdAt: '2022-08-12T10:50:01+02:00'
        data:
          capabilities:
            sendToTransferInstrument:
              requested: true
              requestedLevel: notApplicable
          companyId: YOUR_COMPANY_ID
          merchantId: MC3224X22322535GH8D537TJR
          status: PreActive
    post-merchant.updated-merchant-updated-valid:
      summary: Merchant account verified
      description: Example webhook when verification is succesful
      value:
        type: merchant.updated
        environment: test
        createdAt: '2022-09-20T13:42:31+02:00'
        data:
          capabilities:
            receivePayments:
              allowed: true
              requested: true
              requestedLevel: notApplicable
              verificationStatus: valid
          legalEntityId: LE322KH223222F5GNNW694PZN
          merchantId: YOUR_MERCHANT_ID
          status: PreActive
    post-merchant.updated-merchant-updated-with-errors:
      summary: Merchant account verification failed
      description: Example webhook when verification fails
      value:
        type: merchant.updated
        environment: test
        createdAt: '2022-09-20T13:41:12+02:00'
        data:
          capabilities:
            receivePayments:
              allowed: false
              requested: true
              requestedLevel: notApplicable
              problems:
              - entity:
                  id: LE322KH223222F5GNNW694PZN
                  type: LegalEntity
                verificationErrors:
                - code: '2_8064'
                  message: '''UBO through ownership'' was missing.'
                  remediatingActions:
                  - code: '2_123'
                    message: Add 'organization.entityAssociations' of type 'uboThroughOwnership'
                      to legal entity
                  type: dataMissing
                - code: '1_30'
                  message: Individual details couldn't be verified
                  remediatingActions:
                  - code: '1_300'
                    message: Update individual details
                  subErrors:
                  - code: '1_3000'
                    message: The user couldn't be verified
                    remediatingActions:
                    - code: '1_300'
                      message: Update individual details
                    - code: '1_301'
                      message: Upload an ID document
                    type: invalidInput
                  type: invalidInput
              verificationStatus: invalid
          legalEntityId: LE322KH223222F5GNNW694PZN
          merchantId: YOUR_MERCHANT_ID
          status: PreActive
    post-paymentMethod.created-paymentMethod.created:
      summary: Payment method Visa created
      value:
        createdAt: '2022-01-24T14:59:11+01:00'
        data:
          id: PM3224R223224K5FH4M2K9B86
          merchantId: MERCHANT_ACCOUNT
          status: success
          storeId: ST322LJ223223K5F4SQNR9XL5
          type: visa
        environment: test
        type: paymentMethod.created
    post-paymentMethod.requestRemoved-paymentMethod.requestRemoved:
      summary: Payment method request is removed
      value:
        type: paymentMethod.requestRemoved
        environment: devl
        createdAt: '2023-06-12T18:59:17+02:00'
        data:
          id: PM322WP223224M5HJ6PX77BW8
          storeId: TestStore
          type: amex
          status: dataRequired
          merchantId: TestMerchant
          enabled: false
    post-paymentMethod.requestScheduledForRemoval-paymentMethod.requestScheduledForRemoval:
      summary: Payment method request scheduled for removal
      value:
        type: paymentMethod.requestScheduledForRemoval
        environment: devl
        createdAt: '2023-06-12T19:02:42+02:00'
        data:
          id: PM322WP223224M5HJ6PX77BW8
          storeId: TestStore
          type: visa
          status: updatesExpected
          merchantId: TestMerchant
          enabled: false