After your user selects a grant offer and signs the Terms of Service, you can make an API request to configure the grant for the user. If the request is successful, then Adyen initiates a transfer to settle the grant funds in your user’s balance account.
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 with the Capital financial product enabled. |
| API credentials | You must have a Balance Platform API key (for example, ws[_123456]@BalancePlatform.[YourBalancePlatform]) to access the Capital API. Your API credential must have the following roles:
|
| Capabilities | Make sure that your user have the following capabilities:
|
| Webhooks | Subscribe to the following webhooks: |
| Limitations |
|
| Setup steps | Before you begin, make sure:
|
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.