openapi: 3.1.0
info:
version: '1'
x-publicVersion: true
title: Adyen Configuration Webhooks API
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.
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/paymentInstruments)
associated with the balance account.
items:
$ref: '#/components/schemas/PaymentInstrumentReference'
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-configuration-webhooks-api-openapi.yml