{ "openapi" : "3.1.0", "info" : { "version" : "1", "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).\n\nWhen 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.\n\nSee [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" } ], "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" : { "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." } } } }, "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.\n\nPossible values:\n\n* **pending**: Adyen is running the verification.\n\n* **invalid**: The verification failed. Check if the `errors` array contains more information.\n\n* **valid**: The verification was successful.\n\n* **rejected**: Adyen checked the information and found reasons to not allow the capability.\n", "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.\n\nPossible values:\n\n* **PreActive**: The merchant account has been created. Users cannot access the merchant account in the Customer Area. The account cannot process payments.\n* **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.\n* **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.\n* **Inactive**: Users can access the merchant account in the Customer Area. Payment processing and payouts are disabled.\n* **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 **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" : { "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.\n\nPossible values:\n\n* **PreActive**: The merchant account has been created. Users cannot access the merchant account in the Customer Area. The account cannot process payments.\n* **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.\n* **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.\n* **Inactive**: Users can access the merchant account in the Customer Area. Payment processing and payouts are disabled.\n* **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.\n\nPossible 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.\n\nPossible 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.\n\nPossible 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.\n\nPossible 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" }, "result" : { "description" : "The result of the request to create a payment method.", "enum" : [ "SUCCESS", "FAILURE" ], "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:\n* **valid**\n* **pending**\n* **invalid**\n* **rejected**", "enum" : [ "valid", "pending", "invalid", "rejected" ], "type" : "string" } }, "required" : [ "result", "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.\n\nPossible 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 **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" }, "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" }, "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.\n\nPossible 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 **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" }, "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.\n\nPossible 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.\n\nPossible 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", "result" : "SUCCESS", "storeId" : "ST322LJ223223K5F4SQNR9XL5", "type" : "visa" }, "environment" : "test", "type" : "paymentMethod.created" } } } } }