Limited availability
Cashouts are in pilot phase. Some of the processes and documentation may change as the feature evolves.
When you request a cashout for a user in your platform, you trigger the following transfer events:
- Cashout funding : An incoming transfer is triggered to credit the cashout funds to your user's balance account.
- Fee debit : If you specified a fee, an outgoing transfer is triggered to debit the fee from your user's balance account.
- Funds payout : If you specified a transfer instrument, an outgoing transfer is triggered to pay out the funds from your user's balance account to their transfer instrument.
- Cashout repayment : An outgoing transfer is triggered to debit the cashout funds from your user's balance account. This transfer is triggered on the date when the funds were scheduled to be settled initially.
To track the status of each transfer, 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.
Requirements
To keep track of events related to cashouts in your balance platform, make sure that:
- Your server can receive and accept webhooks.
- You subscribed to the Transfer webhooks and Transaction webhooks in your Balance Platform Customer Area.
Identify webhooks related to cashouts
When your server receives a transfer webhook, you can identify cashout-related webhooks by noting the following values:
The following sections show examples of the webhooks that you would receive based on an example request.
Webhook examples
This section shows examples of webhooks that you receive when you make a cashout request. The webhooks are based on the following scenario:
On January 1, Adyen processed EUR 1000 in sales for one of your users. These sales funds would be settled in your user's balance account on January 3.
If your user needs access to the funds on January 2, you can make a cashout request to Adyen.
The following code shows an example of 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 describe the sequence of webhooks that you receive for each type of cashout-related transfer.
When the cashout request succeeds, Adyen creates a transfer request to credit the cashout funds in your user's balance account. For this transfer, your server receives the following sequence of webhooks:
-
When the transfer request is received, Adyen sends a balancePlatform.transfer.created webhook with the following information:
status: receiveddirection: incomingtype: cashoutFunding
Transfer receivedExpand viewCopy link to code blockCopy code{ "data": { "id": "3K7SQW62YHGU3OLV", "type": "cashoutFunding", "amount": { "value": 100000, "currency": "EUR" }, "events": [ { "id": "EVJN42CMP224223G5KPKJDW106R5NJJ", "type": "accounting", "status": "received", "mutations": [ { "currency": "EUR", "received": 100000 } ], "bookingDate": "2024-01-02T09:44:17+02:00" } ], "reason": "approved", "status": "received", "balances": [ { "currency": "EUR", "received": 100000 } ], "category": "internal", "direction": "incoming", "reference": "CAOT42CLW224223Z5KPKJCNBDX49GD", "description": "CAOT42CLW224223Z5KPKJCNBDX49GD", "categoryData": { "type": "internal" }, "creationDate": "2024-01-02T09:44:05+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description for the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description for the balance account" }, "sequenceNumber": 1, "balancePlatform": "YOUR_BALANCE_PLATFORM", "referenceForBeneficiary": "CAOT42CLW224223Z5KPKJCNBDX49GD" }, "type": "balancePlatform.transfer.created", "environment": "test" } -
When the transfer request is authorised, Adyen sends a balancePlatform.transfer.updated webhook with
statusauthorised. -
When the funds are credited to your user's balance account, Adyen sends a balancePlatform.transfer.updated webhook with the following information:
status: bookedbookingDate: The date when the request is made. For this example, this date is January 2.valueDate: The date when the funds are credited in the balance account, which is the same as the booking date. For this example, the date is January 2.transactionId: The ID of the transaction created for this transfer.
Transfer bookedExpand viewCopy link to code blockCopy code{ "data": { "id": "3K7SQW62YHGU3OLV", "type": "cashoutFunding", "amount": { "value": 100000, "currency": "EUR" }, "events": [ { "id": "EVJN42CMP224223G5KPKJDW106R5NJJ", "type": "accounting", "status": "received", "mutations": [ { "currency": "EUR", "received": 100000 } ], "bookingDate": "2024-01-02T09:44:17+02:00" }, { "id": "EVJN4296L224223G5KPKJDWCQR6ZS4", "type": "accounting", "status": "authorised", "mutations": [ { "currency": "EUR", "received": -100000, "reserved": 100000 } ], "bookingDate": "2024-01-02T09:44:17+02:00" }, { "id": "EVJN42CMP224223G5KPKJDW86S5LSZ", "type": "accounting", "status": "booked", "mutations": [ { "balance": 100000, "currency": "EUR", "received": 0, "reserved": -100000 } ], "valueDate": "2024-01-02T09:44:05+02:00", "bookingDate": "2024-01-02T09:44:17+02:00", "transactionId": "EVJN42CMP224223G5KPKJDW86S5LSZEUR" } ], "reason": "approved", "status": "booked", "balances": [ { "currency": "EUR", "balance": 100000, "received": 0, "reserved": 0 } ], "category": "internal", "direction": "incoming", "reference": "CAOT42CLW224223Z5KPKJCNBDX49GD", "description": "CAOT42CLW224223Z5KPKJCNBDX49GD", "categoryData": { "type": "internal" }, "counterparty": { "balanceAccountId": "CashOutFunding" }, "creationDate": "2024-01-02T09:44:05+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description for the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description for the balance account" }, "sequenceNumber": 3, "balancePlatform": "YOUR_BALANCE_PLATFORM", "referenceForBeneficiary": "CAOT42CLW224223Z5KPKJCNBDX49GD" }, "type": "balancePlatform.transfer.updated", "environment": "test" } -
When the funds are credited, Adyen also sends a balancePlatform.transaction.created webhook, which includes information about the related transaction.
Transaction createdExpand viewCopy link to code blockCopy code{ "data": { "id": "EVJN42CMP224223G5KPKJDW86S5LSZEUR", "amount": { "value": 100000, "currency": "EUR" }, "status": "booked", "transfer": { "id": "3K7SQW62YHGU3OLV", "reference": "CAOT42CLW224223Z5KPKJCNBDX49GD" }, "valueDate": "2024-01-02T09:44:05+02:00", "bookingDate": "2024-01-02T09:44:17+02:00", "creationDate": "2024-01-02T09:44:17+02:00", "accountHolder": { "id": "AH00000000000000000000001", "description": "Your description for the account holder" }, "balanceAccount": { "id": "BA00000000000000000000001", "description": "Your description for the balance account" }, "balancePlatform": "YOUR_BALANCE_PLATFORM" }, "type": "balancePlatform.transaction.created", "environment": "test" }