No momento, esta página não está disponível em português
Fast-payout icon

Webhooks for card payouts

Find out which webhooks Adyen sends for payout-related events.

When a payout is triggered in your platform, Adyen sends the following kinds of webhooks:

This page explains how to identify webhooks related to card payouts and shows examples for the webhooks that you receive for every transfer status.

Requirements

To keep track of payout-related events in your balance platform, ensure that:

Identify payout-related webhooks

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. card
direction The direction of the transfer based on the balance account. outgoing
type Specifies the type of the transfer. cardTransfer

Adyen sends webhooks for the following payout events:

The following sections provide code samples for the events that trigger webhooks. These samples consider a use case where you pay out EUR 100.00 from a balance account to a Mastercard or Visa card.

Payout initiated

When your user initiates a transfer to a Mastercard or Visa card, 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
  • Your user's balanceAccount from which the funds will be deducted
  • Details of the accountHolder linked to your user's balance account.
  • Details of the counterparty in the transfer, which is your user's transfer instrument.
  • The bookingDate when the payout was requested.
  • The id of the corresponding transfer.

The following tabs show examples of balancePlatform.transfer.created webhooks for one-off and recurring payouts.

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. This webhook includes the status authorised.

The following tabs show examples of balancePlatform.transfer.updated webhooks for one-off and recurring payouts.

Payout booked

When the funds are deducted from your user's balance account, Adyen sends a balancePlatform.transfer.updated webhook with:

  • direction: outgoing
  • status: booked
  • events.transactionId: ID of the transaction

This status is not final. The transfer may still fail if, for example, the transfer is rejected by the scheme or issuing bank.

The following tabs show examples of balancePlatform.transfer.updated webhooks for one-off and recurring payouts.

Payout pending

After the funds are deducted from your user's balance account, the transfer is automatically analyzed to ensure that it complies with Adyen's policies. If a transfer is flagged, Adyen reviews the transfer.

In order to speed up the screening process and reduce the amount of manual effort needed, we recommend that you provide as much information as possible in the transfer request. For example, include all counterparty details in the accountHolder object.

In this case, Adyen sends a balancePlatform.transfer.updated webhook with a tracking event, specifying the following trackingData details:

  • status: pending
  • type: internalReview

The following tabs show examples of balancePlatform.transfer.updated webhooks for one-off and recurring payouts.

If the transfer fails Adyen's review process, we send a balancePlatform.transfer.updated webhook with a tracking event, specifying the following trackingData:

  • reason: refusedForRegulatoryReasons
  • status: failed
  • type: internalReview

If this is the case, contact our Support Team.

Payout accepted

When a card payout request is accepted for processing by the card schemes, Adyen sends a balancePlatform.transfer.updated webhook to your server.

The webhook includes a tracking event, which contains the following trackingData details:

  • status: accepted
  • type: confirmation

This event confirms that the scheme will process the payout. You can use this to let your counterparty know that their funds will arrive soon.

The following example shows a balancePlatform.transfer.updated webhook for a payout request that has been accepted:

Payout failed

The payout transfer can fail if it is rejected by an external banking system and any automatic retries are unsuccessful.

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.

The following tabs show examples of balancePlatform.transfer.updated webhooks for one-off and recurring payouts.

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 Final status?
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. No
counterpartyBankUnavailable The counterparty's bank is unavailable for real-time processing. Retry the transfer later or with a different route. No
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. Yes
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. Yes
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. Yes
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. No
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. No
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. No
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. No