Adyen Notification Webhooks API
Adyen sends notifications through webhooks to inform your system about events that occur in the balance platform. These events include, for example, a card user making a payment, or a merchant starting a refund.
OpenAPI Specification
openapi: 3.1.0
info:
version: '1'
x-publicVersion: true
title: Adyen Notification webhooks
description: >-
Adyen sends notifications through webhooks to inform your system about
events that occur in the balance platform. These events include, for
example, a card user making a payment, or a merchant starting a refund. 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 the
webhooks to build your implementation. For example, you can use this
information to update balances in your own dashboards or to keep track of
incoming funds.
x-timestamp: '2022-09-19T22:19:02Z'
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://www.adyen.help/hc/en-us/community/topics
email: [email protected]
x-groups:
- Account holder and balance account
- Payment Instrument
- Authorisation, refund, or transfer requests
- Fund movements
- Reports
tags: []
x-staticResponse: response.json
webhooks:
balancePlatform.accountHolder.created:
post:
tags:
- Account holder and balance account
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-groupName: Account holder and balance account
x-sortIndex: 5
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-accountHolder-created:
$ref: >-
#/components/examples/post-balancePlatform.accountHolder.created-balancePlatform-accountHolder-created
schema:
$ref: '#/components/schemas/AccountHolderNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-accountHolder-created:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.accountHolder.updated:
post:
tags:
- Account holder and balance account
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-groupName: Account holder and balance account
x-sortIndex: 5
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-accountHolder-updated:
$ref: >-
#/components/examples/post-balancePlatform.accountHolder.updated-balancePlatform-accountHolder-updated
schema:
$ref: '#/components/schemas/AccountHolderNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-accountHolder-updated:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.balanceAccount.created:
post:
tags:
- Account holder and 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-groupName: Account holder and balance account
x-sortIndex: 5
security:
- ApiKeyAuth: []
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.balanceAccountSweep.created:
post:
tags:
- Account holder and balance account
summary: Balance account 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-groupName: Account holder and balance account
x-sortIndex: 6
security:
- ApiKeyAuth: []
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:
- Account holder and balance account
summary: Balance account 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-groupName: Account holder and balance account
x-sortIndex: 6
security:
- ApiKeyAuth: []
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:
- Account holder and balance account
summary: Balance account 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-groupName: Account holder and balance account
x-sortIndex: 6
security:
- ApiKeyAuth: []
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.incomingTransfer.created:
post:
tags:
- Fund movements
summary: Incoming transfer created
description: >-
Adyen sends this webhook when there are incoming funds due to a refund
or a fund transfer. Use the `paymentId` to link to the original refund
request or funds transfer request. Check the content of the webhook to
differentiate the events.
* For refunds, the webhook includes the payment instrument to which
funds will be refunded.
* For incoming fund transfers, the webhook only includes information
about the balance account.
x-addedInVersion: '1'
operationId: post-balancePlatform.incomingTransfer.created
x-groupName: Fund movements
x-sortIndex: 1
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-incomingTransfer-created:
$ref: >-
#/components/examples/post-balancePlatform.incomingTransfer.created-balancePlatform-incomingTransfer-created
schema:
$ref: '#/components/schemas/IncomingTransferNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-incomingTransfer-created:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.incomingTransfer.updated:
post:
tags:
- Fund movements
summary: Outgoing transfer updated
description: >-
Adyen sends this webhook when funds were added to the balance account.
This could be due to a refund or a funds transfer. Use the `data.id` to
track the original incoming transfer resource in the
`balancePlatform.incomingTransfer.created` webhook.
The `status` field indicates the event that triggered the webhook.
* For refunds, the `status` is **Refunded**.
* For incoming fund transfers, the `status` is **IncomingTransfer**.
x-addedInVersion: '1'
operationId: post-balancePlatform.incomingTransfer.updated
x-groupName: Fund movements
x-sortIndex: 1
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-incomingTransfer-updated:
$ref: >-
#/components/examples/post-balancePlatform.incomingTransfer.updated-balancePlatform-incomingTransfer-updated
schema:
$ref: '#/components/schemas/IncomingTransferNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-incomingTransfer-updated:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.outgoingTransfer.created:
post:
tags:
- Fund movements
summary: Outgoing transfer created
description: >-
Adyen sends this webhook when funds were deducted from a balance account
due to a capture or a funds transfer. Use the `paymentId` to link to the
original payment authorisation or funds transfer request.
The `status` field indicates the event that triggered the webhook.
* For captures, the `status` will be **Captured**.
* For outgoing fund transfers, the `status` will be
**OutgoingTransfer**.
x-addedInVersion: '1'
operationId: post-balancePlatform.outgoingTransfer.created
x-groupName: Fund movements
x-sortIndex: 1
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-outgoingTransfer-created:
$ref: >-
#/components/examples/post-balancePlatform.outgoingTransfer.created-balancePlatform-outgoingTransfer-created
schema:
$ref: '#/components/schemas/OutgoingTransferNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-outgoingTransfer-created:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.outgoingTransfer.updated:
post:
tags:
- Fund movements
summary: Outgoing transfer updated
description: >-
Adyen sends this webhook when there is updated information after funds
have been deducted from a balance account. For example, if the fund
transfer failed.
Use the `data.id` to track the original outgoing transfer resource from
the `balancePlatform.outgoingTransfer.created` webhook.
x-addedInVersion: '1'
operationId: post-balancePlatform.outgoingTransfer.updated
x-groupName: Fund movements
x-sortIndex: 1
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-outgoingTransfer-updated:
$ref: >-
#/components/examples/post-balancePlatform.outgoingTransfer.updated-balancePlatform-outgoingTransfer-updated
schema:
$ref: '#/components/schemas/OutgoingTransferNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform-outgoingTransfer-updated:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.payment.created:
post:
tags:
- Authorisation, refund, or transfer requests
summary: Payment authorisation, refund, or funds transfer initiated
description: >-
Adyen sends this webhook when a payment authorisation, a refund, or a
funds transfer has been initiated. This webhook only informs your server
of requests. For the actual fund movements, you'll get the information
from the subsequent outgoing or incoming transfer webhooks.
To differentiate the requests, check the content of the webhook.
* For payments, the webhook contains the authorisation result,
information about the processing merchant, and shows a negative amount.
* For refunds, the webhook contains to which payment instrument the funds will be refunded, and shows a positive amount.
* For outgoing or incoming fund transfers, the webhook shows a positive
or negative amount depending on the direction of the transfer, and only
includes information about the balance account.
x-addedInVersion: '1'
operationId: post-balancePlatform.payment.created
x-groupName: Authorisation, refund, or transfer requests
x-sortIndex: 1
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-payment-created-authorized:
$ref: >-
#/components/examples/post-balancePlatform.payment.created-balancePlatform-payment-created-authorized
balancePlatform-payment-created-funds-transfer:
$ref: >-
#/components/examples/post-balancePlatform.payment.created-balancePlatform-payment-created-funds-transfer
balancePlatform-payment-created-refund-requested:
$ref: >-
#/components/examples/post-balancePlatform.payment.created-balancePlatform-payment-created-refund-requested
balancePlatform-payment-created-rejected:
$ref: >-
#/components/examples/post-balancePlatform.payment.created-balancePlatform-payment-created-rejected
schema:
$ref: '#/components/schemas/PaymentNotificationRequest-2'
responses:
'200':
content:
application/json:
examples:
balancePlatform-payment-created-authorized:
$ref: '#/components/examples/WebhookAck'
balancePlatform-payment-created-funds-transfer:
$ref: '#/components/examples/WebhookAck'
balancePlatform-payment-created-refund-requested:
$ref: '#/components/examples/WebhookAck'
balancePlatform-payment-created-rejected:
$ref: '#/components/examples/WebhookAck'
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.payment.updated:
post:
tags:
- Authorisation, refund, or transfer requests
summary: Payment authorisation expired or cancelled
description: >-
Adyen sends this webhook when a payment authorisation has expired or has
been cancelled. Use the `data.id` to track the original payment
authorisation from the `balancePlatform.payment.created` webhook.
x-addedInVersion: '1'
operationId: post-balancePlatform.payment.updated
x-groupName: Authorisation, refund, or transfer requests
x-sortIndex: 1
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform-payment-updated-expired:
$ref: >-
#/components/examples/post-balancePlatform.payment.updated-balancePlatform-payment-updated-expired
balancePlatform-payment-updated-partially-cancelled:
$ref: >-
#/components/examples/post-balancePlatform.payment.updated-balancePlatform-payment-updated-partially-cancelled
balancePlatform-payment-updated-partially-expired:
$ref: >-
#/components/examples/post-balancePlatform.payment.updated-balancePlatform-payment-updated-partially-expired
schema:
$ref: '#/components/schemas/PaymentNotificationRequest-2'
responses:
'200':
content:
application/json:
examples:
balancePlatform-payment-updated-expired:
$ref: '#/components/examples/WebhookAck'
balancePlatform-payment-updated-partially-cancelled:
$ref: '#/components/examples/WebhookAck'
balancePlatform-payment-updated-partially-expired:
$ref: '#/components/examples/WebhookAck'
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 notification does not include the card number when creating virtual
cards. You can only get the card number in the POST response.
operationId: post-balancePlatform.paymentInstrument.created
x-groupName: Payment Instrument
x-sortIndex: 3
security:
- ApiKeyAuth: []
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-groupName: Payment Instrument
x-sortIndex: 3
security:
- ApiKeyAuth: []
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.
balancePlatform.report.created:
post:
tags:
- Reports
summary: Report generated
description: >-
Adyen sends this webhook after a report is generated and ready to be
downloaded. The webhook contains the URL at which the report can be
downloaded.
Before you download reports, ask your Adyen contact for your report
credentials. You must use your the credentials to authenticate your GET
request.
operationId: post-balancePlatform.report.created
x-groupName: Reports
x-sortIndex: 7
security:
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
balancePlatform.report.created:
$ref: >-
#/components/examples/post-balancePlatform.report.created-balancePlatform.report.created
schema:
$ref: '#/components/schemas/ReportNotificationRequest'
responses:
'200':
content:
application/json:
examples:
balancePlatform.report.created:
$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:
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__resParam_id)
associated with the account holder. Adyen performs a verification
process against the legal entity of the account holder.
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**: 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](https://www.iana.org/time-zones) of the account
holder. For example, **Europe/Amsterdam**.
If not set, the time zone of the balance account will be used. For
possible values, see the [list of time zone
codes](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
type: string
required:
- legalEntityId
- id
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/JSONObject'
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/JSONObject'
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
AccountHolderNotificationData:
properties:
accountHolder:
description: >-
Contains information about the account holder resource that
triggered the event.
$ref: '#/components/schemas/AccountHolder'
balancePlatform:
description: Unique identifier of the balance platform.
type: string
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 notification.
enum:
- balancePlatform.accountHolder.updated
- balancePlatform.accountHolder.created
type: string
required:
- environment
- type
- data
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
# --- truncated at 32 KB (135 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/notification-webhooks-openapi-original.yml