Make a cashout request

Limited availability
Cashouts are in pilot phase. Some of the processes and documentation may change as the feature evolves.

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.

To make a cashout request:

1. (Recommended) Get the pending balance on the user's balance account: Ensure that your user has enough funds for the cashout.
2. Initiate the cashout: Specify the details of the cashout in an API request.
3. 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.

Requirements

Before you initiate a cashout:

• Contact our Support Team to enable cashout for your platform.
• Ensure that your API credential has roles to use the Transfers API.
• Ensure that the sales day settlement model is enabled in your user's balance account.
• Ensure that your account and your user's account have the receiveFromBalanceAccount capability.
• Ensure that your user's account has the sendToBalanceAccount.
• Ensure that your user's account has the sendToTransferInstrument . This is only required for cashout requests that include a transferInstrumentId.

  From LEM API v3, this capability is verified at the level of the transfer instrument, such as a bank account. This means that transfers are possible to a verified transfer instrument independently of the verification status of other transfer instruments that the legal entity has.

• Ensure that your server receives and accepts webhooks.

(Recommended) Get the pending balance on the balance account

Before initiating 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 the pending balance to your user, so that they know the maximum amount that they can ask for.
• Check that the amount that your user is asking for is less or equal to the pending balance.

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

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

Initiate a cashout

To initiate a cashout, make a POST /cashouts request, specifying 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 balance.
amount.currency		The currency of the cashout amount.
transferInstrumentId	Required to pay out the funds to the user's transfer instrument.	The unique identifier of the user's transfer instrument to which the funds are paid out. If you do not provide this value, the funds are not paid out, but remain in the user's balance account.
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.

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

curl https://balanceplatform-api-test.adyen.com/btl/v4/cashouts \
-H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
-H 'content-type: application/json' \
-X POST \
-d '{
    "instructingBalanceAccountId": "BA00000000000000000000001",
    "transferInstrumentId": "SE00000000000000000000001",
    "amount": {
        "currency": "EUR",
        "value": 100000
    },
    "fee": {
        "amount":{
            "currency": "EUR",
            "value": 1000
        }
    }
}'

The following tabs show the responses that you receive after a successful or failed request.

{
    "id": "CAOT0000000000000000000000001",
    "amount": {
        "currency": "EUR",
        "value": 100000
    },
    "fee": {
        "amount": {
            "currency": "EUR",
            "value": 1000
        }
    },
    "instructingBalanceAccountId": "BA00000000000000000000001",
    "transerInstrumentId": "SE00000000000000000000001",
    "transfers": [
        {
            "amount": {
                "currency": "EUR",
                "value": 100000
            },
            "category": "internal",
            "id": "400F6060JMB1I0AB",
            "type": "cashoutRepayment"
        },
        {
            "amount": {
                "currency": "EUR",
                "value": 1000
            },
            "category": "internal",
            "id": "400F6060JMB1I0AA",
            "type": "cashoutFee"
        }
    ]
}

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 platform.
• 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 Balance Platform Customer Area.

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

See also