Adyen sends webhooks to inform your system about incoming and outgoing transfers in your platform. You can use these 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.
openapi: 3.1.0
info:
version: '4'
x-publicVersion: true
title: Adyen Transfer webhooks
description: >-
Adyen sends webhooks to inform your system about incoming and outgoing
transfers in your platform. You can use these 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.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: General
x-staticResponse: response.json
webhooks:
balancePlatform.transfer.created:
post:
tags:
- General
summary: Transfer created
description: Adyen sends this webhook when there are fund movements on your platform.
x-addedInVersion: '1'
operationId: post-balancePlatform.transfer.created
x-sortIndex: 0
x-methodName: transferCreated
security:
- BasicAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferNotificationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
balancePlatform.transfer.updated:
post:
tags:
- General
summary: Transfer updated
description: >+
Adyen sends this webhook when the status of a transfer changes. Use the
`data.id` to track the original transfer resource in the
[balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/1/post/balancePlatform.transfer.created)
webhook.
The `status` field indicates the event that triggered the webhook.
x-addedInVersion: '1'
operationId: post-balancePlatform.transfer.updated
x-sortIndex: 0
x-methodName: transferUpdated
security:
- BasicAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferNotificationRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BalancePlatformNotificationResponse'
description: OK - the request has succeeded.
components:
schemas:
AULocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The bank account number, without separators or whitespace.
maxLength: 9
minLength: 5
type: string
bsbCode:
description: >-
The 6-digit [Bank State Branch (BSB)
code](https://en.wikipedia.org/wiki/Bank_state_branch), without
separators or whitespace.
maxLength: 6
minLength: 6
type: string
type:
default: auLocal
description: '**auLocal**'
enum:
- auLocal
type: string
required:
- type
- accountNumber
- bsbCode
type: object
AdditionalBankIdentification:
properties:
code:
description: The value of the additional bank identification.
type: string
type:
description: >-
The type of additional bank identification, depending on the
country.
Possible values:
* **gbSortCode**: The 6-digit [UK sort code](https://en.wikipedia.org/wiki/Sort_code), without separators or spaces
* **usRoutingNumber**: The 9-digit [routing number](https://en.wikipedia.org/wiki/ABA_routing_transit_number), without separators or spaces.
enum:
- gbSortCode
- usRoutingNumber
type: string
type: object
Address:
properties:
city:
description: The name of the city.
type: string
country:
description: >-
The two-character ISO 3166-1 alpha-2 country code. For example,
**US**, **NL**, or **GB**.
type: string
line1:
description: First line of the street address.
type: string
line2:
description: Second line of the street address.
type: string
postalCode:
description: |-
The postal code.
Maximum length:
* 5 digits for an address in the US.
* 10 characters for an address in all other countries.
type: string
stateOrProvince:
description: >-
The two-letter 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
required:
- 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
AmountAdjustment:
properties:
amount:
x-addedInVersion: '3'
description: The adjustment amount.
$ref: '#/components/schemas/Amount'
amountAdjustmentType:
x-addedInVersion: '3'
description: >-
The type of markup that is applied to an authorised payment.
Possible values: **exchange**, **forexMarkup**, **authHoldReserve**,
**atmMarkup**.
enum:
- atmMarkup
- authHoldReserve
- exchange
- forexMarkup
type: string
basepoints:
x-addedInVersion: '3'
description: The basepoints associated with the applied markup.
format: int32
type: integer
type: object
BRLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The bank account number, without separators or whitespace.
maxLength: 10
minLength: 1
type: string
bankCode:
description: The 3-digit bank code, with leading zeros.
maxLength: 3
minLength: 3
type: string
branchNumber:
description: The bank account branch number, without separators or whitespace.
maxLength: 4
minLength: 1
type: string
type:
default: brLocal
description: '**brLocal**'
enum:
- brLocal
type: string
required:
- type
- branchNumber
- accountNumber
- bankCode
type: object
BalanceMutation:
properties:
balance:
x-addedInVersion: '3'
description: >-
The amount in the payment's currency that is debited or credited on
the balance accounting register.
format: int64
type: integer
currency:
x-addedInVersion: '3'
description: >-
The three-character [ISO currency
code](https://docs.adyen.com/development-resources/currency-codes).
type: string
received:
x-addedInVersion: '3'
description: >-
The amount in the payment's currency that is debited or credited on
the received accounting register.
format: int64
type: integer
reserved:
x-addedInVersion: '3'
description: >-
The amount in the payment's currency that is debited or credited on
the reserved accounting register.
format: int64
type: integer
type: object
BalancePlatformNotificationResponse:
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
BankAccountV3:
properties:
accountHolder:
description: Information about the owner of the bank account.
$ref: '#/components/schemas/PartyIdentification'
accountIdentification:
description: >-
Contains the bank account details. The fields required in this
object depend on the country of the bank account and the currency of
the transfer.
oneOf:
- $ref: '#/components/schemas/AULocalAccountIdentification'
- $ref: '#/components/schemas/BRLocalAccountIdentification'
- $ref: '#/components/schemas/CALocalAccountIdentification'
- $ref: '#/components/schemas/CZLocalAccountIdentification'
- $ref: '#/components/schemas/DKLocalAccountIdentification'
- $ref: '#/components/schemas/HKLocalAccountIdentification'
- $ref: '#/components/schemas/HULocalAccountIdentification'
- $ref: '#/components/schemas/IbanAccountIdentification'
- $ref: '#/components/schemas/NOLocalAccountIdentification'
- $ref: '#/components/schemas/NZLocalAccountIdentification'
- $ref: '#/components/schemas/NumberAndBicAccountIdentification'
- $ref: '#/components/schemas/PLLocalAccountIdentification'
- $ref: '#/components/schemas/SELocalAccountIdentification'
- $ref: '#/components/schemas/SGLocalAccountIdentification'
- $ref: '#/components/schemas/UKLocalAccountIdentification'
- $ref: '#/components/schemas/USLocalAccountIdentification'
required:
- accountIdentification
- accountHolder
type: object
BankCategoryData:
additionalProperties: false
properties:
priority:
x-addedInVersion: '4'
description: >-
The priority for the bank transfer. This sets the speed at which the
transfer is sent and the fees that you have to pay. Required for
transfers with `category` **bank**.
Possible values:
* **regular**: For normal, low-value transactions.
* **fast**: Faster way to transfer funds but has higher fees.
Recommended for high-priority, low-value transactions.
* **wire**: Fastest way to transfer funds but has the highest fees.
Recommended for high-priority, high-value transactions.
* **instant**: Instant way to transfer funds in [SEPA
countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).
* **crossBorder**: High-value transfer to a recipient in a different
country.
* **internal**: Transfer to an Adyen-issued business bank account
(by bank account number/IBAN).
enum:
- crossBorder
- fast
- instant
- internal
- regular
- wire
type: string
type:
default: bank
description: '**bank**'
enum:
- bank
type: string
type: object
CALocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: >-
The 5- to 12-digit bank account number, without separators or
whitespace.
maxLength: 12
minLength: 5
type: string
accountType:
default: checking
description: >-
The bank account type.
Possible values: **checking** or **savings**. Defaults to
**checking**.
enum:
- checking
- savings
type: string
institutionNumber:
description: The 3-digit institution number, without separators or whitespace.
maxLength: 3
minLength: 3
type: string
transitNumber:
description: The 5-digit transit number, without separators or whitespace.
maxLength: 5
minLength: 5
type: string
type:
default: caLocal
description: '**caLocal**'
enum:
- caLocal
type: string
required:
- type
- accountNumber
- institutionNumber
- transitNumber
type: object
CZLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: >-
The 2- to 16-digit bank account number (Číslo účtu) in the following
format:
- The optional prefix (předčíslí).
- The required second part (základní část) which must be at least
two non-zero digits.
Examples:
- **19-123457** (with prefix)
- **123457** (without prefix)
- **000019-0000123457** (with prefix, normalized)
- **000000-0000123457** (without prefix, normalized)
maxLength: 17
minLength: 2
type: string
bankCode:
description: The 4-digit bank code (Kód banky), without separators or whitespace.
maxLength: 4
minLength: 4
type: string
type:
default: czLocal
description: '**czLocal**'
enum:
- czLocal
type: string
required:
- type
- accountNumber
- bankCode
type: object
CounterpartyV3:
properties:
balanceAccountId:
description: >-
Unique identifier of the [balance
account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
type: string
bankAccount:
description: Contains information about the bank account.
$ref: '#/components/schemas/BankAccountV3'
merchant:
description: Contains information about the merchant.
$ref: '#/components/schemas/MerchantData'
transferInstrumentId:
description: >-
Unique identifier of the [transfer
instrument](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments__resParam_id).
type: string
type: object
DKLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: >-
The 4-10 digits bank account number (Kontonummer) (without
separators or whitespace).
maxLength: 10
minLength: 4
type: string
bankCode:
description: >-
The 4-digit bank code (Registreringsnummer) (without separators or
whitespace).
maxLength: 4
minLength: 4
type: string
type:
default: dkLocal
description: '**dkLocal**'
enum:
- dkLocal
type: string
required:
- type
- accountNumber
- bankCode
type: object
HKLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: >-
The 9- to 15-character bank account number (alphanumeric), without
separators or whitespace. Starts with the 3-digit branch code.
maxLength: 15
minLength: 9
type: string
clearingCode:
description: The 3-digit clearing code, without separators or whitespace.
maxLength: 3
minLength: 3
type: string
type:
default: hkLocal
description: '**hkLocal**'
enum:
- hkLocal
type: string
required:
- type
- accountNumber
- clearingCode
type: object
HULocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The 24-digit bank account number, without separators or whitespace.
maxLength: 24
minLength: 24
type: string
type:
default: huLocal
description: '**huLocal**'
enum:
- huLocal
type: string
required:
- type
- accountNumber
type: object
IbanAccountIdentification:
additionalProperties: false
properties:
iban:
description: >-
The international bank account number as defined in the
[ISO-13616](https://www.iso.org/standard/81090.html) standard.
type: string
type:
default: iban
description: '**iban**'
enum:
- iban
type: string
required:
- type
- iban
type: object
InternalCategoryData:
additionalProperties: false
properties:
modificationMerchantReference:
x-addedInVersion: '4'
description: The capture's merchant reference included in the transfer.
type: string
modificationPspReference:
x-addedInVersion: '4'
description: The capture reference included in the transfer.
type: string
type:
default: internal
description: '**internal**'
enum:
- internal
type: string
type: object
IssuedCard:
additionalProperties: false
properties:
authorisationType:
x-addedInVersion: '4'
description: >-
The authorisation type. For example, **defaultAuthorisation**,
**preAuthorisation**, **finalAuthorisation**
type: string
panEntryMode:
x-addedInVersion: '4'
description: >-
Indicates the method used for entering the PAN to initiate a
transaction.
Possible values: **manual**, **chip**, **magstripe**,
**contactless**, **cof**, **ecommerce**, **token**.
enum:
- chip
- cof
- contactless
- ecommerce
- magstripe
- manual
- token
type: string
processingType:
x-addedInVersion: '4'
description: >-
Contains information about how the payment was processed. For
example, **ecommerce** for online or **pos** for in-person payments.
enum:
- atmWithdraw
- balanceInquiry
- ecommerce
- moto
- pos
- purchaseWithCashback
- recurring
- token
type: string
relayedAuthorisationData:
x-addedInVersion: '4'
description: >-
If you are using relayed authorisation, this object contains
information from the relayed authorisation response from your
server.
$ref: '#/components/schemas/RelayedAuthorisationData'
schemeTraceId:
x-addedInVersion: '4'
description: >-
The identifier of the original payment provided by the scheme. The
Id could be alphanumeric or numeric depending on the scheme. The
schemeTraceID should be referring to an original
schemeUniqueTransactionID provided in an earlier payment (not
necessarily processed by Adyen). Instances of available
schemeTraceId is authAdjustment or recurring payments.
type: string
schemeUniqueTransactionId:
x-addedInVersion: '4'
description: >-
The unique identifier created by the scheme. The ID could be
alphanumeric or numeric depending on the scheme.
type: string
type:
default: issuedCard
description: '**issuedCard**'
enum:
- issuedCard
type: string
validationFacts:
x-addedInVersion: '4'
description: >-
The evaluation of the validation facts. See [validation
checks](https://docs.adyen.com/issuing/validation-checks) for more
information.
items:
$ref: '#/components/schemas/TransferNotificationValidationFact'
type: array
type: object
MerchantData:
properties:
acquirerId:
description: The unique identifier of the merchant's acquirer.
type: string
mcc:
description: The merchant category code.
type: string
merchantId:
description: The merchant identifier.
type: string
nameLocation:
description: Contains the merchant's name and location.
$ref: '#/components/schemas/NameLocation'
postalCode:
description: The merchant postal code.
type: string
type: object
Modification:
properties:
direction:
x-addedInVersion: '3'
description: The direction of the money movement.
type: string
id:
x-addedInVersion: '3'
description: Our reference for the modification.
type: string
reference:
x-addedInVersion: '3'
description: >-
Your reference for the modification, used internally within your
platform.
type: string
status:
x-addedInVersion: '3'
description: The status of the transfer event.
enum:
- approvalPending
- atmWithdrawal
- atmWithdrawalReversalPending
- atmWithdrawalReversed
- authAdjustmentAuthorised
- authAdjustmentError
- authAdjustmentRefused
- authorised
- bankTransfer
- bankTransferPending
- booked
- bookingPending
- cancelled
- capturePending
- captureReversalPending
- captureReversed
- captured
- capturedExternally
- chargeback
- chargebackExternally
- chargebackPending
- chargebackReversalPending
- chargebackReversed
- credited
- depositCorrection
- depositCorrectionPending
- dispute
- disputeClosed
- disputeExpired
- disputeNeedsReview
- error
- expired
- failed
- fee
- feePending
- internalTransfer
- internalTransferPending
- invoiceDeduction
- invoiceDeductionPending
- manualCorrectionPending
- manuallyCorrected
- matchedStatement
- matchedStatementPending
- merchantPayin
- merchantPayinPending
- merchantPayinReversed
- merchantPayinReversedPending
- miscCost
- miscCostPending
- paymentCost
- paymentCostPending
- received
- refundPending
- refundReversalPending
- refundReversed
- refunded
- refundedExternally
- refused
- reserveAdjustment
- reserveAdjustmentPending
- returned
- secondChargeback
- secondChargebackPending
- undefined
type: string
type:
x-addedInVersion: '3'
description: The type of transfer modification.
type: string
type: object
NOLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The 11-digit bank account number, without separators or whitespace.
maxLength: 11
minLength: 11
type: string
type:
default: noLocal
description: '**noLocal**'
enum:
- noLocal
type: string
required:
- type
- accountNumber
type: object
NZLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: >-
The 15-16 digit bank account number. The first 2 digits are the bank
number, the next 4 digits are the branch number, the next 7 digits
are the account number, and the final 2-3 digits are the suffix.
maxLength: 16
minLength: 15
type: string
type:
default: nzLocal
description: '**nzLocal**'
enum:
- nzLocal
type: string
required:
- type
- accountNumber
type: object
NameLocation:
properties:
city:
description: The city where the merchant is located.
type: string
country:
description: >-
The country where the merchant is located in [three-letter country
code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.
type: string
countryOfOrigin:
description: >-
The home country in [three-digit country
code](https://en.wikipedia.org/wiki/ISO_3166-1_numeric) format, used
for government-controlled merchants such as embassies.
type: string
name:
description: The name of the merchant's shop or service.
type: string
rawData:
description: The raw data.
type: string
state:
description: The state where the merchant is located.
type: string
type: object
NumberAndBicAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: >-
The bank account number, without separators or whitespace. The
length and format depends on the bank or country.
maxLength: 34
type: string
additionalBankIdentification:
description: >-
Additional identification codes of the bank. Some banks may require
these identifiers for cross-border transfers.
$ref: '#/components/schemas/AdditionalBankIdentification'
bic:
description: The bank's 8- or 11-character BIC or SWIFT code.
maxLength: 11
minLength: 8
type: string
type:
default: numberAndBic
description: '**numberAndBic**'
enum:
- numberAndBic
type: string
required:
- type
- accountNumber
- bic
type: object
PLLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: >-
The 26-digit bank account number ([Numer
rachunku](https://pl.wikipedia.org/wiki/Numer_Rachunku_Bankowego)),
without separators or whitespace.
maxLength: 26
minLength: 26
type: string
type:
default: plLocal
description: '**plLocal**'
enum:
- plLocal
type: string
required:
- type
- accountNumber
type: object
PartyIdentification:
properties:
address:
description: Address of the bank account owner.
$ref: '#/components/schemas/Address'
dateOfBirth:
description: >-
The date of birth of the individual in
[ISO-8601](https://www.w3.org/TR/NOTE-datetime) format. For example,
**YYYY-MM-DD**. Should not be before January 1, 1900.
Allowed only when `type` is **individual**.
format: date
type: string
firstName:
description: |-
First name of the individual.
Allowed only when `type` is **individual**.
type: string
fullName:
description: The name of the entity.
type: string
lastName:
description: |-
Last name of the individual.
Allowed only when `type` is **individual**.
type: string
reference:
description: >-
A unique reference to identify the party or counterparty involved in
transfers. This identifier ensures consistency and uniqueness
throughout all transactions initiated to and from the same party.
For example, your client's unique wallet or payee ID.
maxLength: 150
type: string
type:
default: unknown
description: |-
The type of entity that owns the bank account.
Possible values: **individual**, **organization**, or **unknown**.
enum:
- individual
- organization
- unknown
type: string
required:
- fullName
type: object
PaymentInstrument:
properties:
description:
description: The description of the resource.
type: string
id:
description: The unique identifier of the resource.
type: string
reference:
description: The reference for the resource.
type: string
tokenType:
x-addedInVersion: '3'
description: The type of wallet the network token is associated with.
type: string
type: object
PlatformPayment:
additionalProperties: false
properties:
modificationMerchantReference:
x-addedInVersion: '4'
description: The capture's merchant reference included in the transfer.
type: string
modificationPspReference:
x-addedInVersion: '4'
description: The capture reference included in the transfer.
type: string
paymentMerchantReference:
x-addedInVersion: '4'
description: The payment's merchant reference included in the transfer.
type: string
platformPaymentType:
x-addedInVersion: '4'
description: The type of the related split.
enum:
- AcquiringFees
- AdyenCommission
- AdyenFees
- AdyenMarkup
- BalanceAccount
- Commission
- Default
- Interchange
- PaymentFee
- Remainder
- SchemeFee
- TopUp
- VAT
type: string
pspPaymentReference:
x-addedInVersion: '4'
description: The payment reference included in the transfer.
type: string
type:
default: platformPayment
description: '**platformPayment**'
enum:
- platformPayment
type: string
type: object
RelayedAuthorisationData:
properties:
metadata:
x-addedInVersion: '3'
additionalProperties:
type: string
description: >-
Contains key-value pairs of your references and descriptions, for
example, `customId`:`your-own-custom-field-12345`.
type: object
reference:
x-addedInVersion: '3'
description: Your reference for the relayed authorisation data.
type: string
type: object
Resource:
properties:
balancePlatform:
description: The unique identifier of the balance platform.
type: string
creationDate:
description: >-
The date and time when the event was triggered, in ISO 8601 extended
format. For example, **2020-12-18T10:15:30+01:00**.
format: date-time
type: string
id:
description: The ID of the resource.
type: string
type: object
ResourceReference:
properties:
description:
description: The description of the resource.
type: string
id:
description: The unique identifier of the resource.
type: string
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/transfer-webhooks-openapi-original.yml