Adyen Management Webhooks API
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.
OpenAPI Specification
openapi: 3.1.0
info:
version: '3'
x-publicVersion: true
title: Adyen 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 a 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
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-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-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-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-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-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
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:
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