Make a cashout request

When you make a cashout, your user's pending funds are instantly made available in your user's balance account. In your cashout request, you can also specify to pay out the funds to the user's transfer instrument.

Requirements

Before you initiate a cashout, take into account the following requirements.

How it works

To make a cashout request:

1. (Recommended) Check whether the transfer instrument supports instant payouts: Calculate a transfer route for the transfer instrument.
2. (Recommended) Get the pending balance on the user's balance account: Ensure that your user has enough funds for the cashout.
3. Initiate the cashout: Specify the details of the cashout in an API request.
4. Get updates on the status of the cashout: Listen to webhooks to check the status of the cashout.

The following sections explain how to perform these steps.

(Recommended) Check whether the transfer instrument supports instant payouts

Before you initiate a cashout for a user, we recommend that you check whether the counterparty bank supports instant payouts. This reduces the risk of failed cashouts.

To check whether the transfer instrument supports instant payouts:

1. Make a POST /transferRoutes/calculate request, specifying the following parameters:

   Parameter	Required	Description
   balancePlatform		The unique identifier of your balance platform.
   balanceAccountId		The unique identifier of your balance account that will initiate the cashout.
   counterparty.transferInstrumentId		The unique identifier of the counterparty transfer instrument.
   currency		The three-character ISO currency code of the transfer.
   category		The type of transfer. Set to bank.
   country		The two-character ISO country code of the counterparty. For example, US or NL.
   priorities		An array that contains the priorities that you want to calculate transfer routes for. Set to instant.

   The following code shows an example of this request.

2. In the response, verify that you receive an object with the transferRoutes.priority set to instant.

(Recommended) Get the pending available balance on the balance account

Before you initiate a cashout for a user, we recommend that you get the pending balance on the user's balance account. By doing this, you can:

• Show to your users the balance that is available for cashouts. This helps your users know the maximum amount that they can ask for.
• Check that the amount that your user is asking for is less than or equal to the pending balance.

To get the pending available balance on your user's balance account:

1. Make a GET /balanceAccounts/{id} request.
2. In the response, note the value of the balances.pendingAvailable parameter.

If the pending available balance is negative, inform your user that the balance available for cashouts is 0.

Initiate a cashout

To initiate a cashout:

1. Make a POST /cashouts request and specify the following parameters in the request body:

   Parameter	Required	Description
   instructingBalanceAccountId		The unique identifier of the balance account where the cashout amount is settled.
   amount.value		The amount of the cashout. This is the amount that is settled and paid out to your user. This value cannot be higher than the pending available balance.
   amount.currency		The currency of the cashout amount.
   counterparty.transferInstrumentId		The unique identifier of the user's transfer instrument to which the funds are paid out. Use case: Required to pay out the funds to the user's transfer instrument. If you do not provide this value, the funds are not paid out, but remain in the user's balance account.
   description		Your description of the cashout transfer. This description is used by most banks as the transfer description. Allowed and returned only when you provide the counterparty.transferInstrumentId field.
   fee.amount.value		The amount (in minor units) of the fee that your platform charges for the cashout. Note that: The fee amount cannot be higher than the cashout amount. The sum of the cashout and fee amounts cannot be higher than the pending balance.
   fee.amount.currency		The currency of the fee that your platform charges for the cashout. This value must be the same as amount.currency.
   referenceForBeneficiary		The reference that is sent to the recipient of a cashout transfer. Allowed and returned only when you provide the counterparty.transferInstrumentId field.

   The following example shows a cashout request for EUR 1000, with a fee of EUR 10.

2. If the request succeeds, note the following response parameters, which help you identify cashout-related transfers:

   Response parameter	Description
   id	The unique identifier of the cashout.
   transfers	An array of objects that contain information about the transfers created in relation to the cashout.
   transfers.type	Specifies the type of transfer data that the object contains. Possible values: cashoutRepayment: Corresponds to the transfer created to deduct the cashout amount after settlement. cashoutFee: Corresponds to the transfer created to debit the cashout fee from the user's balance account.

   The following example shows a successful response for a created cashout.

After you make the cashout request, Adyen processes it asynchronously. To track any updates related to your cashout request, use the webhooks that Adyen sends to your server.

Get updates on the status of the cashout

A cashout involves multiple funds transfers, which you can track by listening to webhooks. Webhooks inform you about any status change in the transfers, and whether the transfers succeed or fail.

Adyen sends three types of webhooks for each transfer:

• balancePlatform.transfer.created, which informs your server that funds will be transferred to or from a balance account in your marketplace.
• balancePlatform.transfer.updated, which informs your server of changes in the status of the transfer.
• balancePlatform.transaction.created, which informs your server when funds have been debited from or credited to a balance account.

To listen to these webhooks:

1. Ensure that your server can receive and accept webhooks.
2. Subscribe to Transfer webhooks and Transaction webhooks in your Customer Area.

Alternatively, you can view the transfer details in your Customer Area.

Troubleshooting

A cashout request can fail because of communication issues with the bank, or because of invalid request parameters.

If the cashout request is successful, but the payout to your user's transfer instrument fails, the cashout request is reversed. This means that:

• The cashout amount is returned to the user's balance account and settled as pending available balance.
• The fee charged to your user is returned to the user's balance account and settled as pending available balance.
• Your marketplace is not charged any fees for the failed cashout.

To retry a failed cashout, you must initiate a new POST /cashouts request.

Error responses

If the request fails, you receive an error response with information about the error.

Error responses for invalid cashout requests can include the following fields:

• title: Specifies the type of error.
• detail: Specifies the cause of the error.
• invalidFields: Specifies whether one or more fields contain invalid information.

The following subsections describe some of the errors and messages that you can get when you make cashout requests.

See also