After your user selects a grant offer and signs the Terms of Service, you can make an API request to configure a grant for your user. If the request is successful, then Adyen initiates a transfer to settle the grant funds in your user’s balance account.
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 balanceAccountId and transferInstrumentId are 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.
The response contains 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.
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.