After your user selects a grant offer, you can make an API request to configure the grant for them. If the request is successful, then Adyen initiates a transfer to settle the grant funds in your user’s balance account. To activate the grant, the user may need to take additional actions, such as signing the Terms of Service.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | You must have an Adyen for Platforms integration. |
| API credentials | You must have a Balance Platform API key (for example, ws[_123456]@BalancePlatform.[YourBalancePlatform]) to access the Capital API. Ensure that you have asked your Adyen contact to assign the following role to your API credential:
|
| Capabilities | Make sure that your user's account holder has the following capabilities:
|
| Webhooks | Ensure that your server can receive and accept standard webhooks. Subscribe to the following webhooks: |
| Limitations | Currently, only one disbursement per grant is allowed. We are working on enabling multiple disbursements to different balance accounts. |
| Setup steps | Before you begin:
|
How it works
When a user selects an offer and signs the Terms of Service, the necessary capabilities are enabled. The grant can then be disbursed to the user. For that:
- Make an API request to configure a grant.
- Listen to the webhooks to get information about the status of the grant and payout.
1. Configure a grant
To configure a grant:
-
Make a POST /grants request, specifying the following parameters:
Parameter Required Description counterparty.balanceAccountId The identifier of the balance account that belongs to the receiving account holder. Pass this parameter if you choose to pay out to the balance account of the user. counterparty.transferInstrumentId The identifier of the transfer instrument that belongs to the legal entity of the account holder. Pass this parameter if you choose to pay out to the transfer instrument of the user. grantAccountId 
The identifier of the grant account. Reach out to your Adyen contact to get this value. grantOfferId The identifier of the grant offer that has been selected by the user. If both
balanceAccountIdandtransferInstrumentIdare not provided in the request, the grant is paid out to the account holder's primaryBalanceAccount.Here's an example of how to request a payout of a grant to the specified balance account.
-
In the response, note the following parameters:
Parameter Description id The identifier of the grant reference. grantAccountId The identifier of the grant account used to account for the grant. grantOfferId The identifier of the grant offer that has been selected by the receiving account holder. counterparty An object containing the details of the receiving account holder. amount An object containing the amount of the grant, in minor units. fee An object containing the fee amount. repayment An object containing the repayment amount and configuration, in basis points. status The status of the grant.
Requests using POST /grants are processed asynchronously. You will receive a response to your API request, but you must wait for the webhook to know the final result of a request.
2. Get updates
Adyen will send the following webhooks to your server to update you about the grant and payout status.
| Webhook type | Description |
|---|---|
| balancePlatform.grants.created | The grant has been configured. |
| balancePlatform.grants.updated | The grant has been fully repaid, reconfigured, or written off in case the user did not pay back all outstanding funds. |
| balancePlatform.transfer.created | The outgoing or incoming grant transfer request has been received. |
| balancePlatform.transfer.updated | The outgoing or incoming grant transfer request has been authorized and/or booked. |
| balancePlatform.transaction.created | The funds have been paid out to the balance account or the payment instrument. |
To keep track of webhooks, make sure that your server can receive and accept webhooks.