When a payout is triggered in your platform, Adyen sends two kinds of webhooks:
- balancePlatform.transfer.created, which informs your server that an outgoing transfer is initiated from a balance account in your platform.
- balancePlatform.transfer.updated, which informs your server of the transfer status changes.
To keep track of payout-related events in your platform, ensure that:
- Your server can receive and accept webhooks.
- You subscribed to the Transfer webhooks in your Balance Platform Customer Area.
You can identify transfer webhooks triggered by payout-related events by looking at the following values:
Parameter | Description | Value |
---|---|---|
category | Specifies the category of the transfer. | bank |
direction | The direction of the transfer based on the balance account. | outgoing |
type | Specifies the type of the transfer. | bankTransfer |
Adyen sends webhooks for the following payout events:
- Payout initiated
- Payout authorised
- Payout booked
- Payout tracking
- Payout returned
- Payout failed
- Reason codes
The following sections provide code samples for the events that trigger webhooks. These samples consider a use case where you pay out EUR 10.00 from a balance account to a transfer instrument.
Payout initiated
After an on-demand payout is triggered, Adyen sends a balancePlatform.transfer.created webhook to inform your server that an outgoing transfer request has been created. The webhook provides information about the transfer, such as:
- The
amount
of the payout - The
reference
for the payout - The
referenceForbeneficiary
- The
accountHolder
information of the recipient - The
balanceAccount
from which the funds will be deducted
Payout authorised
When the transfer request for the payout is authorised, Adyen sends a balancePlatform.transfer.updated webhook to inform your server that the transfer amount has been reserved on the account.
Payout booked
When the funds are deducted from your balance account, Adyen sends a balancePlatform.transfer.updated webhook with the transactionId
and the status
booked. This status is not final, the payout may still fail, for example if the transfer is rejected by the external banking system.
Payout tracking
If the transfer is completed, then Adyen sends a balancePlatform.transfer.updated webhook with a tracking
event specifying the estimatedArrivalTime
. This is the estimated time when the funds will be credited in the counterparty bank account.
If a transfer with priority
instant is completed, then Adyen sends a balancePlatform.transfer.updated webhook to confirm that the funds have been credited. The webhook includes a tracking
event with the tracking status
credited.
Payout returned
If the payout transfer is returned by the counterparty's bank, then Adyen sends a balancePlatform.transfer.updated webhook with:
status
: returned- The
transactionId
- The
reason
for not accepting the transfer. For more information, see Reason codes.
Payout failed
The payout transfer can fail if it is rejected by an external banking system and any potential automatic retry attempts are unsuccessful. For payouts using instant bank transfers with end-to-end confirmation from the counterparty's bank, this is the status when counterparty's bank rejects the transfer.
When a payout transfer fails, Adyen sends a balancePlatform.transfer.updated webhook with:
status
: failed- The
transactionId
- The
reason
for the failure. For more information, see Reason codes.
Reason codes
The following table describes the reasons why a transfer may be rejected or returned by the counterparty's bank.
Reason code | Description | Remediating action | ||
---|---|---|---|---|
counterpartyBankUnavailable |
The counterparty's bank is unavailable for real-time processing. | Retry the transfer later or with a different route. | ||
counterpartyAccountNotFound |
The counterparty's bank is unable to locate the account with the provided details. | Check the transfer instrument's details provided in the transfer and retry. | ||
counterpartyAccountClosed |
The counterparty's bank reported that the account exists, but it is closed. | Check the transfer instrument's details provided in the transfer and retry. | ||
counterpartyAccountBlocked |
The counterparty's bank reported that the account is blocked or suspended . | Check the transfer instrument's details provided in the transfer and retry. | ||
refusedByCounterpartyBank |
The counterparty's bank refused the transfer without providing any further information regarding the underlying reason. | Check the transfer instrument's details provided in the transfer and/or contact the counterparty's bank. | ||
amountLimitExceeded |
The counterparty's bank or the payment system rejected this transfer because the value is too high. | Retry the transfer with a lower amount or with a different route. | ||
counterpartyAddressRequired |
The counterparty's bank requires the account holder's address to credit this transfer to the account. | Retry the transfer with full street address. | ||
counterpartyBankTimedOut |
The counterparty 's bank timed out while trying to process this request in real-time. | Retry the transfer later or with a different route. | ||
unknown |
No specific reason is known by Adyen for the failure, or the reported reason does not correspond to any of the codes above. | Check the transfer instrument's details provided in the transfer and retry. If problem persists, further manual investigation might be needed. |