--- title: "Disburse a grant" description: "Learn how to make a request for a grant and disburse the funds to your user's account." url: "https://docs.adyen.com/capital/make-grant-request" source_url: "https://docs.adyen.com/capital/make-grant-request.md" canonical: "https://docs.adyen.com/capital/make-grant-request" last_modified: "2026-05-12T18:42:28+02:00" language: "en" --- # Disburse a grant Learn how to make a request for a grant and disburse the funds to your user's account. 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](/capital/manage-access#manage-api-credentials) (for example, **ws\[\_123456]@BalancePlatform.\[YourBalancePlatform]**) to access the [Capital API](https://docs.adyen.com/api-explorer/capital/latest/overview). Your API credential must have the following roles:- **Balance Platform Capital Configuration role** - **Balance Platform Capital Grant Initiation role** | | **Capabilities** | Make sure that your user have the following [capabilities](/capital/manage-user-capabilities):- **getGrantOffers** - **receiveGrants** | | **Webhooks** | Subscribe to the following webhooks:- [Capital webhooks](https://docs.adyen.com/api-explorer/capital-webhooks/latest/overview) - [Transfer webhooks](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/overview) | | **Limitations** | * Your user must operate in one of the [supported countries/regions](/capital#supported-countriesregions). * Currently, only one disbursement per grant is allowed. We are working on enabling multiple disbursements to different balance accounts. | | **Setup steps** | Before you begin, make sure:* You reached out to your Adyen contact to set up the necessary configurations to add the Capital financial product to your integration. For more details, see our [Integration checklist](/capital/integration-checklist). * You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. * Your user [selected a grant offer](/capital/get-grant-offers) and [signed the Terms of Service](/capital/terms-of-service). | ## 1. Configure a grant To configure a grant: 1. Make a POST [/grants](https://docs.adyen.com/api-explorer/capital/latest/post/grants) request, specifying the following parameters: | Parameter | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [counterparty.balanceAccountId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-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](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-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](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-grantAccountId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The identifier of the grant account. Reach out to your Adyen contact to get this value. | | [grantOfferId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-grantOfferId) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The identifier of the grant offer that has been selected by the user. | If `balanceAccountId` is not provided in the request, the grant is paid out to the account holder's [primaryBalanceAccount](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/accountHolders/\(id\)#responses-200-primaryBalanceAccount). Here's an example of how to request a payout of a grant to the specified balance account. **Disburse a grant** ```bash curl https://balanceplatform-api-test.adyen.com/capital/v1/grants \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "grantAccountId": "CG00000000000000000000001", "grantOfferId": "0000000000000001", "counterparty": { "balanceAccountId": "BA00000000000000000000001" } }' ``` 2. In the response, note the following parameters: | Parameter | Description | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [id](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-id) | The unique identifier of the grant. | | [grantAccountId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-grantAccountId) | The identifier of the [grant account](#grant-account) used to account for the grant. | | [grantOfferId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-grantOfferId) | The unique identifier for the related grant offer, which determines the grant conditions. | | [counterparty](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-counterparty) | An object containing the details of the receiving account holder. | | [status](https://docs.adyen.com/api-explorer/capital/latest/post/grants#responses-200-status) | The status of the grant. | **Response** ```json { "grantAccountId": "CG00000000000000000000001", "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantOfferId": "0000000000000001", "id": "GR00000000000000000000001", "status": { "code": "Requested" }, "balances": { "principal": 0, "fee": 0, "total": 0, "currency": "EUR" } } ``` Requests using POST [/grants](https://docs.adyen.com/api-explorer/capital/latest/post/grants) are processed asynchronously. You will receive a response to your API request, but you must wait for the [webhook](/capital/make-grant-request?tab=grant_configured_0_1) to know the final result of a request. ## 2. Get updates Adyen will send the webhook messages for the following event types to your server to update you about the grant and fund transfer status. | Event type | Description | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | [balancePlatform.grants.created](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.created) | The grant has been configured. | | [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/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](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) | The outgoing or incoming grant transfer request has been received. | | [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) | The outgoing or incoming grant transfer request has been authorized and/or booked. | | [balancePlatform.transaction.created](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/post/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](/development-resources/webhooks). ### Tab: Grant configured After the requested grant has been configured on the Adyen side, you will receive a webhook message with the event type `balancePlatform.grants.created`. **Grant configured webhook** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Requested" } } }, "environment": "test", "timestamp": "2026-01-21T19:56:42.107Z", "type": "balancePlatform.grants.created" } ``` ### Tab: Transfer received After the grant has been configured, you will receive a webhook message with the event type [balancePlatform.transfer.created](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.created) and the `status` **received**. **Incoming transfer received** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "received", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "EUR" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 1, "balances": [ { "currency": "EUR", "received": 1850000 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "EUR", "received": 1850000 } ] } ], "eventId": "EV0000000000000000000000000001" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.336Z", "type": "balancePlatform.transfer.created" } ``` ### Tab: Transfer authorised After the grant payout request has been received, you will receive a webhook message with the event type [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) and the `status` **authorized**. **Incoming transfer authorized** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "authorised", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "EUR" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 2, "balances": [ { "reserved": 1850000, "currency": "EUR", "received": 0 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "EUR", "received": 1850000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": 1850000, "currency": "EUR", "received": -1850000 } ] } ], "eventId": "EV0000000000000000000000000002" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.336Z", "type": "balancePlatform.transfer.updated" } ``` ### Tab: Transfer booked After the grant payout request has been authorized, you will receive another webhook message with the event type [balancePlatform.transfer.updated](https://docs.adyen.com/api-explorer/transfer-webhooks/latest/post/balancePlatform.transfer.updated) and the `status` **booked**. **Incoming transfer booked** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "1OUUU768NUBED14V", "creationDate": "2025-10-15T18:53:08+02:00", "createdAt": "2025-10-15T18:52:54+02:00", "status": "booked", "reason": "approved", "direction": "incoming", "balanceAccount": { "id": "BA00000000000000000000001", "description": "", "reference": "BA-ref-01" }, "accountHolder": { "id": "AH00000000000000000000001", "reference": "AH-ref-01" }, "category": "grants", "type": "grant", "amount": { "value": 1850000, "currency": "EUR" }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "description": "GR00000000000000000000001", "updatedAt": "2025-10-15T18:53:08+02:00", "sequenceNumber": 3, "balances": [ { "reserved": 0, "balance": 1850000, "currency": "EUR", "received": 0 } ], "events": [ { "id": "EV0000000000000000000000000001", "status": "received", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "currency": "EUR", "received": 1850000 } ] }, { "id": "EV0000000000000000000000000002", "status": "authorised", "bookingDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": 1850000, "currency": "EUR", "received": -1850000 } ] }, { "id": "EV0000000000000000000000000003", "status": "booked", "transactionId": "EV000000000000000000000000000EUR", "bookingDate": "2025-10-15T18:53:08+02:00", "valueDate": "2025-10-15T18:53:08+02:00", "type": "accounting", "mutations": [ { "reserved": -1850000, "balance": 1850000, "currency": "EUR", "received": 0 } ] } ], "eventId": "EV0000000000000000000000000003" }, "environment": "test", "timestamp": "2025-10-15T16:53:11.36Z", "type": "balancePlatform.transfer.updated" } ``` ### Tab: Grant paid out After the funds have been paid out to the receiving balance account or payment instrument, you will receive a webhook message with the event type `balancePlatform.transaction.created`. **Grant paid out webhook** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "3JFBE65XIXOPZ30N", "accountHolderId": "AH00000000000000000000001", "amount": { "currency": "EUR", "value": -1850000 }, "balanceAccountId": "BA00000000000000000000001", "bookingDate": "2023-01-09T16:36:35+01:00", "counterparty": { "balanceAccountId": "BA00000000000000000000002" }, "createdAt": "2023-01-09T16:36:34+01:00", "description": "GR00000000000000000000001", "instructedAmount": { "currency": "EUR", "value": -1850000 }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000001", "transferId": "1OUUU768NUBED14V", "valueDate": "2025-10-15T18:54:08+02:00" }, "environment": "test", "type": "balancePlatform.transaction.created" } ``` ### Tab: Grant repaid After the account holder fully repays the grant, you will receive a webhook message with the event type `balancePlatform.grants.updated`. **Grant repaid webhook** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000001", "status": { "code": "Repaid" } } }, "environment": "test", "timestamp": "2026-01-21T19:59:10.153Z", "type": "balancePlatform.grants.updated" } ``` ## Next steps [Get grant details](/capital/get-grant-balances) [Learn how to get information about all grants in your balance platform.](/capital/get-grant-balances) [Manage disbursements](/capital/manage-disbursements) [Learn how to get and update configurations of a disbursement.](/capital/manage-disbursements)