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 tags: - name: Merchant account - name: Payment method - name: Terminal management 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-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: 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-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: 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-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: schema: $ref: '#/components/schemas/PaymentMethodNotificationResponse' description: OK - the request has succeeded. paymentMethodRequest.removed: 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-paymentMethodRequest.removed x-sortIndex: 3 x-methodName: paymentMethodRequestRemoved security: - BasicAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentMethodRequestRemovedNotificationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaymentMethodNotificationResponse' description: OK - the request has succeeded. paymentMethodRequest.scheduledForRemoval: 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/platforms/onboard-users). x-addedInVersion: '2' operationId: post-paymentMethodRequest.scheduledForRemoval x-sortIndex: 2 x-methodName: paymentMethodRequestScheduledForRemoval security: - BasicAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentMethodScheduledForRemovalNotificationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaymentMethodNotificationResponse' description: OK - the request has succeeded. terminalAssignment.completed: post: tags: - Terminal management summary: Terminal assignment completed description: A request to [reassign a terminal](https://docs.adyen.com/api-explorer/Management/3/post/terminals/(terminalId)/reassign) was completed. x-addedInVersion: '3' operationId: post-terminalAssignment.completed x-sortIndex: 3 x-methodName: terminalAssignmentCompleted security: - BasicAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TerminalAssignmentNotificationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TerminalAssignmentNotificationResponse' description: OK - the request has succeeded. terminalBoarding.triggered: post: tags: - Terminal management summary: Result of terminal boarding description: The boarding of a payment terminal succeeded. x-addedInVersion: '1' operationId: post-terminalBoarding.triggered x-sortIndex: 2 x-methodName: resultOfTerminalBoarding security: - BasicAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TerminalBoardingNotificationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TerminalBoardingNotificationResponse' description: OK - the request has succeeded. terminalSettings.modified: post: tags: - Terminal management summary: Terminal settings updated description: A request to [update terminal settings](https://docs.adyen.com/api-explorer/Management/latest/patch/terminals/(terminalId)/terminalSettings) was completed. x-addedInVersion: '1' operationId: post-terminalSettings.modified x-sortIndex: 1 x-methodName: terminalSettingsUpdated security: - BasicAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/TerminalSettingsNotificationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TerminalSettingsNotificationResponse' description: OK - the request has succeeded. components: schemas: AccountCapabilityData: additionalProperties: false 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 verificationDeadline: description: The verification deadline for the capability that will be disallowed if verification errors are not resolved. format: date-time 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: additionalProperties: false 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: 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 AccountUpdateNotificationData: additionalProperties: false 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: additionalProperties: false 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: additionalProperties: false 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: additionalProperties: false 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: additionalProperties: false 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: additionalProperties: false 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: additionalProperties: false 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: additionalProperties: false 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: 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 PaymentMethodRequestRemovedNotificationRequest: additionalProperties: false 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: - paymentMethodRequest.removed type: string required: - environment - createdAt - data - type type: object PaymentMethodScheduledForRemovalNotificationRequest: additionalProperties: false 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: - paymentMethodRequest.scheduledForRemoval type: string required: - environment - createdAt - data - type type: object RemediatingAction: additionalProperties: false 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 TerminalAssignmentNotificationRequest: additionalProperties: false properties: assignedToAccount: description: The unique identifier of the merchant/company account to which the terminal is assigned. type: string assignedToStore: description: The unique identifier of the store to which the terminal is assigned. type: string eventDate: description: The date and time when an event has been completed. type: string pspReference: description: The PSP reference of the request from which the notification originates. type: string uniqueTerminalId: description: The unique identifier of the terminal. type: string required: - uniqueTerminalId - pspReference - eventDate - assignedToAccount type: object TerminalAssignmentNotificationResponse: 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 TerminalBoardingData: additionalProperties: false properties: companyId: description: The unique identifier of the company account. type: string merchantId: description: The unique identifier of the merchant account. type: string storeId: description: The unique identifier of the store. type: string uniqueTerminalId: description: The unique identifier of the terminal. type: string required: - uniqueTerminalId - companyId type: object TerminalBoardingNotificationRequest: additionalProperties: false properties: createdAt: description: Timestamp for when the webhook was created. format: date-time type: string data: description: Contains event details. $ref: '#/components/schemas/TerminalBoardingData' environment: description: 'The environment from which the webhook originated. Possible values: **test**, **live**.' type: string type: description: Type of notification. enum: - terminalBoarding.triggered type: string required: - environment - createdAt - data - type type: object TerminalBoardingNotificationResponse: 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 TerminalSettingsData: additionalProperties: false properties: companyId: description: The unique identifier of the company account. type: string merchantId: description: The unique identifier of the merchant account. type: string storeId: description: The unique identifier of the store. type: string terminalId: description: The unique identifier of the terminal. type: string updateSource: description: Indicates whether the terminal settings were updated using the Customer Area or the Management API. enum: - Customer Area - Management Api type: string user: description: The user that updated the terminal settings. Can be Adyen or your API credential username. type: string required: - user - updateSource type: object TerminalSettingsNotificationRequest: additionalProperties: false properties: createdAt: description: Timestamp for when the webhook was created. format: date-time type: string data: description: Contains event details. $ref: '#/components/schemas/TerminalSettingsData' environment: description: 'The environment from which the webhook originated. Possible values: **test**, **live**.' type: string type: description: Type of notification. enum: - terminalSettings.modified type: string required: - environment - createdAt - data - type type: object TerminalSettingsNotificationResponse: 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 VerificationError: additionalProperties: false 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: additionalProperties: false 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: 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