Adyen sends webhooks to inform your system about events that occur in your platform. These events include, for example, when an account holders capabilities are updated, or when a sweep configuration is created or updated.
openapi: 3.1.0
info:
version: '1'
x-publicVersion: true
title: Adyen Configuration webhooks
description: >-
Adyen sends webhooks to inform your system about events that occur in your
platform. These events include, for example, when an account holders
capabilities are updated, or when a sweep configuration is created or
updated. 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. You
can use these webhooks to build your implementation. For example, you can
use this information to update internal statuses when the status of a
capability is changed.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: Account holder
- name: Balance account
- name: Payment instrument
- name: Card order
x-staticResponse: response.json
webhooks:
balancePlatform.accountHolder.created:
post:
tags:
- Account holder
summary: Account holder created
description: >-
Adyen sends this webhook when you successfully [create an account
holder](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/accountHolders).
operationId: post-balancePlatform.accountHolder.created
x-sortIndex: 1
x-methodName: accountHolderCreated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-accountHolder-created:
$ref: >-
#/components/examples/post-balancePlatform.accountHolder.created-balancePlatform-accountHolder-created
balancePlatform-accountHolder-created-lem-v3:
$ref: >-
#/components/examples/post-balancePlatform.accountHolder.created-balancePlatform-accountHolder-created-lem-v3
schema:
$ref: '#/components/schemas/AccountHolderNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-accountHolder-created:
$ref: '#/components/examples/WebhookAck'
balancePlatform-accountHolder-created-lem-v3:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.accountHolder.updated:
post:
tags:
- Account holder
summary: Account holder updated
description: >-
Adyen sends this webhook when you successfully [update an account
holder](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/accountHolders/_id_).
operationId: post-balancePlatform.accountHolder.updated
x-sortIndex: 2
x-methodName: accountHolderUpdated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-accountHolder-updated:
$ref: >-
#/components/examples/post-balancePlatform.accountHolder.updated-balancePlatform-accountHolder-updated
balancePlatform-accountHolder-updated-lem-v3:
$ref: >-
#/components/examples/post-balancePlatform.accountHolder.updated-balancePlatform-accountHolder-updated-lem-v3
schema:
$ref: '#/components/schemas/AccountHolderNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-accountHolder-updated:
$ref: '#/components/examples/WebhookAck'
balancePlatform-accountHolder-updated-lem-v3:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.balanceAccount.created:
post:
tags:
- Balance account
summary: Balance account created
description: >-
Adyen sends this webhook when you successfully [create a balance
account](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts).
operationId: post-balancePlatform.balanceAccount.created
x-sortIndex: 1
x-methodName: balanceAccountCreated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-balanceAccount-created:
$ref: >-
#/components/examples/post-balancePlatform.balanceAccount.created-balancePlatform-balanceAccount-created
schema:
$ref: '#/components/schemas/BalanceAccountNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-balanceAccount-created:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.balanceAccount.updated:
post:
tags:
- Balance account
summary: Balance account updated
description: >-
Adyen sends this webhook when you successfully [update a balance
account](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balanceAccounts/_id_).
operationId: post-balancePlatform.balanceAccount.updated
x-sortIndex: 2
x-methodName: balanceAccountUpdated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-balanceAccount-updated:
$ref: >-
#/components/examples/post-balancePlatform.balanceAccount.updated-balancePlatform-balanceAccount-updated
schema:
$ref: '#/components/schemas/BalanceAccountNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-balanceAccount-updated:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.balanceAccountSweep.created:
post:
tags:
- Balance account
summary: Sweep created
description: >-
Adyen sends this webhook when you successfully [create a
sweep](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balanceAccounts/_balanceAccountId_/sweeps).
operationId: post-balancePlatform.balanceAccountSweep.created
x-sortIndex: 3
x-methodName: sweepCreated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-sweep-created:
$ref: >-
#/components/examples/post-balancePlatform.balanceAccountSweep.created-balancePlatform-sweep-created
schema:
$ref: '#/components/schemas/SweepConfigurationNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-sweep-created:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.balanceAccountSweep.deleted:
post:
tags:
- Balance account
summary: Sweep deleted
description: >-
Adyen sends this webhook when you successfully [delete a
sweep](https://docs.adyen.com/api-explorer/balanceplatform/latest/delete/balanceAccounts/_balanceAccountId_/sweeps/_sweepId_).
operationId: post-balancePlatform.balanceAccountSweep.deleted
x-sortIndex: 5
x-methodName: sweepDeleted
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-sweep-deleted:
$ref: >-
#/components/examples/post-balancePlatform.balanceAccountSweep.deleted-balancePlatform-sweep-deleted
schema:
$ref: '#/components/schemas/SweepConfigurationNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-sweep-deleted:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.balanceAccountSweep.updated:
post:
tags:
- Balance account
summary: Sweep updated
description: >-
Adyen sends this webhook when you successfully [update a
sweep](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balanceAccounts/_balanceAccountId_/sweeps/_sweepId_).
operationId: post-balancePlatform.balanceAccountSweep.updated
x-sortIndex: 4
x-methodName: sweepUpdated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-sweep-updated:
$ref: >-
#/components/examples/post-balancePlatform.balanceAccountSweep.updated-balancePlatform-sweep-updated
schema:
$ref: '#/components/schemas/SweepConfigurationNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-sweep-updated:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.cardorder.created:
post:
tags:
- Card order
summary: Card order created
description: >-
Adyen sends this webhook to indicate a successful creation of a card
order after you create a [payment
instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments)
of `type` **card** and `formFactor` **physical**.
operationId: post-balancePlatform.cardorder.created
x-sortIndex: 1
x-methodName: cardOrderCreated
security:
- BasicAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CardOrderNotificationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.cardorder.updated:
post:
tags:
- Card order
summary: Card order updated
description: Adyen sends this webhook when there is an update in card order status.
operationId: post-balancePlatform.cardorder.updated
x-sortIndex: 2
x-methodName: cardOrderUpdated
security:
- BasicAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CardOrderNotificationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.paymentInstrument.created:
post:
tags:
- Payment instrument
summary: Payment instrument created
description: >-
Adyen sends this webhook when you successfully [create a payment
instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments).
>The webhook does not include the card number when creating virtual
cards. You can only get the card number in the response of the POST
[/paymentInstruments](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/paymentInstruments#responses-200-card-number)
request.
operationId: post-balancePlatform.paymentInstrument.created
x-sortIndex: 1
x-methodName: paymentInstrumentCreated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-paymentInstrument-created:
$ref: >-
#/components/examples/post-balancePlatform.paymentInstrument.created-balancePlatform-paymentInstrument-created
schema:
$ref: '#/components/schemas/PaymentNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-paymentInstrument-created:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.paymentInstrument.updated:
post:
tags:
- Payment instrument
summary: Payment instrument updated
description: >-
Adyen sends this webhook when you successfully [update a payment
instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/paymentInstruments/_id_).
operationId: post-balancePlatform.paymentInstrument.updated
x-sortIndex: 2
x-methodName: paymentInstrumentUpdated
security:
- BasicAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-paymentInstrument-updated:
$ref: >-
#/components/examples/post-balancePlatform.paymentInstrument.updated-balancePlatform-paymentInstrument-updated
schema:
$ref: '#/components/schemas/PaymentNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-paymentInstrument-updated:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
components:
schemas:
AccountHolder:
properties:
balancePlatform:
description: >-
The unique identifier of the [balance
platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id)
to which the account holder belongs. Required in the request if your
API credentials can be used for multiple balance platforms.
type: string
capabilities:
additionalProperties:
$ref: '#/components/schemas/AccountHolderCapability'
description: >-
Contains key-value pairs that specify the actions that an account
holder can do in your platform. The key is a capability required for
your integration. For example, **issueCard** for Issuing. The value
is an object containing the settings for the capability.
type: object
contactDetails:
deprecated: true
description: Contact details of the account holder.
$ref: '#/components/schemas/ContactDetails'
description:
description: Your description for the account holder, maximum 300 characters.
maxLength: 300
type: string
id:
description: The unique identifier of the account holder.
type: string
legalEntityId:
description: >-
The unique identifier of the [legal
entity](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities#responses-200-id)
associated with the account holder. Adyen performs a verification
process against the legal entity of the account holder.
type: string
metadata:
additionalProperties:
type: string
description: >-
A set of key and value pairs for general use.
The keys do not have specific names and may be used for storing
miscellaneous data as desired.
> Note that during an update of metadata, the omission of existing
key-value pairs will result in the deletion of those key-value
pairs.
type: object
migratedAccountHolderCode:
description: >-
The unique identifier of the migrated account holder in the classic
integration.
type: string
primaryBalanceAccount:
description: >-
The ID of the account holder's primary balance account. By default,
this is set to the first balance account that you create for the
account holder. To assign a different balance account, send a PATCH
request.
type: string
reference:
description: Your reference for the account holder, maximum 150 characters.
maxLength: 150
type: string
status:
description: >-
The status of the account holder.
Possible values:
* **Active**: The account holder is active. This is the default status when creating an account holder.
* **Inactive (Deprecated)**: The account holder is temporarily inactive due to missing KYC details. You can set the account back to active by providing the missing KYC details.
* **Suspended**: The account holder is permanently deactivated by Adyen. This action cannot be undone.
* **Closed**: The account holder is permanently deactivated by you.
This action cannot be undone.
enum:
- Active
- Closed
- Inactive
- Suspended
type: string
timeZone:
description: >-
The time zone of the account holder. For example,
**Europe/Amsterdam**.
Defaults to the time zone of the balance platform if no time zone is
set. For possible values, see the [list of time zone
codes](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
type: string
verificationDeadlines:
description: >-
List of verification deadlines and the capabilities that will be
disallowed if verification errors are not resolved.
items:
$ref: '#/components/schemas/VerificationDeadline'
type: array
required:
- legalEntityId
- id
type: object
AccountHolderCapability:
properties:
allowed:
description: >-
Indicates whether the capability is allowed. Adyen sets this to
**true** if the verification is successful and the account holder is
permitted to use the capability.
type: boolean
allowedLevel:
description: |-
The capability level that is allowed for the account holder.
Possible values: **notApplicable**, **low**, **medium**, **high**.
enum:
- high
- low
- medium
- notApplicable
type: string
allowedSettings:
description: >-
A JSON object containing the settings that are allowed for the
account holder.
$ref: '#/components/schemas/CapabilitySettings'
enabled:
description: >-
Indicates whether the capability is enabled. If **false**, the
capability is temporarily disabled for the account holder.
type: boolean
problems:
description: >-
Contains verification errors and the actions that you can take to
resolve them.
items:
$ref: '#/components/schemas/CapabilityProblem'
type: array
requested:
description: >-
Indicates whether the capability is requested. To check whether the
account holder is permitted to use the capability, refer to the
`allowed` field.
type: boolean
requestedLevel:
description: >-
The requested level of the capability. Some capabilities, such as
those used in [card
issuing](https://docs.adyen.com/issuing/add-capabilities#capability-levels),
have different levels. Levels increase the capability, but also
require additional checks and increased monitoring.
Possible values: **notApplicable**, **low**, **medium**, **high**.
enum:
- high
- low
- medium
- notApplicable
type: string
requestedSettings:
description: >-
A JSON object containing the settings that were requested for the
account holder.
$ref: '#/components/schemas/CapabilitySettings'
transferInstruments:
description: >-
Contains the status of the transfer instruments associated with this
capability.
items:
$ref: '#/components/schemas/AccountSupportingEntityCapability'
type: array
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 has been successfully completed.
* **rejected**: Adyen has verified the information, but found
reasons to not allow the capability.
enum:
- invalid
- pending
- rejected
- valid
type: string
type: object
AccountHolderNotificationData:
properties:
accountHolder:
description: >-
Contains information about the account holder resource that
triggered the event.
$ref: '#/components/schemas/AccountHolder'
balancePlatform:
description: The unique identifier of the balance platform.
type: string
type: object
AccountHolderNotificationRequest:
properties:
data:
description: Contains event details.
$ref: '#/components/schemas/AccountHolderNotificationData'
environment:
description: |-
The environment from which the webhook originated.
Possible values: **test**, **live**.
type: string
type:
description: Type of webhook.
enum:
- balancePlatform.accountHolder.updated
- balancePlatform.accountHolder.created
type: string
required:
- environment
- type
- data
type: object
AccountSupportingEntityCapability:
properties:
allowed:
description: >-
Indicates whether the supporting entity capability is allowed. Adyen
sets this to **true** if the verification is successful and the
account holder is permitted to use the capability.
type: boolean
allowedLevel:
description: |-
The capability level that is allowed for the account holder.
Possible values: **notApplicable**, **low**, **medium**, **high**.
enum:
- high
- low
- medium
- notApplicable
type: string
enabled:
description: >-
Indicates whether the capability is enabled. If **false**, the
capability is temporarily disabled for the account holder.
type: boolean
id:
description: The ID of the supporting entity.
type: string
requested:
description: >-
Indicates whether the capability is requested. To check whether the
account holder is permitted to use the capability, refer to the
`allowed` field.
type: boolean
requestedLevel:
description: >-
The requested level of the capability. Some capabilities, such as
those used in [card
issuing](https://docs.adyen.com/issuing/add-capabilities#capability-levels),
have different levels. Levels increase the capability, but also
require additional checks and increased monitoring.
Possible values: **notApplicable**, **low**, **medium**, **high**.
enum:
- high
- low
- medium
- notApplicable
type: string
verificationStatus:
description: >
The status of the verification checks for the supporting entity
capability.
Possible values:
* **pending**: Adyen is running the verification.
* **invalid**: The verification failed. Check if the `errors` array
contains more information.
* **valid**: The verification has been successfully completed.
* **rejected**: Adyen has verified the information, but found
reasons to not allow the capability.
enum:
- invalid
- pending
- rejected
- valid
type: string
type: object
Address:
properties:
city:
description: 'The name of the city. Maximum length: 3000 characters.'
maxLength: 3000
type: string
country:
description: >-
The two-character ISO-3166-1 alpha-2 country code. For example,
**US**.
> If you don't know the country or are not collecting the country
from the shopper, provide `country` as `ZZ`.
type: string
houseNumberOrName:
description: 'The number or name of the house. Maximum length: 3000 characters.'
maxLength: 3000
type: string
postalCode:
description: >-
A maximum of five digits for an address in the US, or a maximum of
ten characters for an address in all other countries.
type: string
stateOrProvince:
description: >-
The two-character ISO 3166-2 state or province code. For example,
**CA** in the US or **ON** in Canada.
> Required for the US and Canada.
type: string
street:
description: >-
The name of the street. Maximum length: 3000 characters.
> The house number should not be included in this field; it should
be separately provided via `houseNumberOrName`.
maxLength: 3000
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
type: object
Amount:
properties:
currency:
description: >-
The three-character [ISO currency
code](https://docs.adyen.com/development-resources/currency-codes).
maxLength: 3
minLength: 3
type: string
value:
description: >-
The amount of the transaction, in [minor
units](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
- value
- currency
type: object
Authentication:
properties:
email:
description: The email address where the one-time password (OTP) is sent.
type: string
password:
description: >-
The password used for 3D Secure password-based authentication. The
value must be between 1 to 30 characters and must only contain the
following supported characters.
* Characters between **a-z**, **A-Z**, and **0-9**
* Special characters: **äöüßÄÖÜ+-*/ç%()=?!~#'",;:$&àùòâôûáúó**
maxLength: 30
minLength: 1
type: string
phone:
description: |-
The phone number where the one-time password (OTP) is sent.
This object must have:
* A `type` set to **mobile**.
* A `number` with a valid country code.
* A `number` with more than 4 digits, excluding the country code.
>Make sure to verify that the card user owns the phone number.
$ref: '#/components/schemas/Phone'
type: object
Balance:
properties:
available:
description: The remaining amount available for spending.
format: int64
type: integer
balance:
description: The total amount in the balance.
format: int64
type: integer
currency:
description: >-
The three-character [ISO currency
code](https://docs.adyen.com/development-resources/currency-codes)
of the balance.
type: string
pending:
description: >-
The amount pending to be paid out but not yet available in the
balance.
format: int64
type: integer
reserved:
description: >-
The amount reserved for payments that have been authorised, but have
not been captured yet.
format: int64
type: integer
required:
- currency
- balance
- reserved
- available
type: object
BalanceAccount:
properties:
accountHolderId:
description: >-
The unique identifier of the [account
holder](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/accountHolders__resParam_id)
associated with the balance account.
type: string
balances:
description: List of balances with the amount and currency.
items:
$ref: '#/components/schemas/Balance'
type: array
defaultCurrencyCode:
description: >-
The default three-character [ISO currency
code](https://docs.adyen.com/development-resources/currency-codes)
of the balance account.
The default value is **EUR**.
> After a balance account is created, you cannot change its default
currency.
type: string
description:
description: >-
A human-readable description of the balance account, maximum 300
characters. You can use this parameter to distinguish between
multiple balance accounts under an account holder.
maxLength: 300
type: string
id:
description: The unique identifier of the balance account.
type: string
metadata:
additionalProperties:
type: string
description: >-
A set of key and value pairs for general use.
The keys do not have specific names and may be used for storing
miscellaneous data as desired.
> Note that during an update of metadata, the omission of existing
key-value pairs will result in the deletion of those key-value
pairs.
type: object
migratedAccountCode:
description: >-
The unique identifier of the account of the migrated account holder
in the classic integration.
type: string
paymentInstruments:
description: >-
List of [payment
instruments](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/payme
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/configuration-webhooks-openapi-original.yml