--- title: "Renew a grant" description: "Learn how to configure a subsequent grant that renews a partially repaid grant for your user." url: "https://docs.adyen.com/capital/renew-grant" source_url: "https://docs.adyen.com/capital/renew-grant.md" canonical: "https://docs.adyen.com/capital/renew-grant" last_modified: "2026-06-15T16:12:33+02:00" language: "en" --- # Renew a grant Learn how to configure a subsequent grant that renews a partially repaid grant for your user. [View source](/capital/renew-grant.md) **Limited availability**\ Grant renewal is currently in a pilot phase. To request access, reach out to your Adyen contact. *** Users do not have to wait until the prior grant is fully repaid to receive additional financing. When a grant is partially paid off and meets [eligibility requirements for grant renewal](/capital/additional-financing#eligibility), you can configure a subsequent grant. Adyen disburses the full subsequent grant amount and reserves the outstanding principal of the prior grant for repayment. This page covers the process of renewing a grant. Throughout this page, *prior grant* refers to the active grant that is being renewed, and *subsequent grant* refers to the new grant that renews it. ## 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 that supports Capital. | | **API credentials** | You must have a [Balance Platform API key](/capital/manage-access#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 has 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) - [Transaction webhooks](https://docs.adyen.com/api-explorer/transaction-webhooks/latest/overview) | | **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, make sure:- You followed our [compliance guidelines for Capital](/capital/compliance-guidelines) when creating user interfaces, marketing materials, and other processes. - You reviewed the eligibility requirements and conditions for [grant renewal](/capital/additional-financing). | ## How it works The grant renewal process includes the following steps: 1. [Get a notification](#grant-eligibility) of grant eligibility for grant renewal. 2. [Get offers](#get-offers) for the account holder and present those that meet the renewal minimum. 3. [Present the user with the new Terms of Service](#present-tos). 4. [Configure a subsequent grant](#configure-renewal-grant). 5. [Get updates](#get-updates) about the grant status. ## 1. Get a notification of grant eligibility for grant renewal Listen to the [balancePlatform.grants.updated](https://docs.adyen.com/api-explorer/capital-webhooks/latest/post/balancePlatform.grants.updated) webhook. When a grant becomes eligible for grant renewal, Adyen sends a webhook with the following key fields: * `renewal.eligible`: **true** * `renewal.minimumAmount`: The minimum financing amount the user must accept to renew the grant. * `id`: The unique identifier of the grant that is eligible for renewal. Alternatively, you can get this information by making the GET [/grants](https://docs.adyen.com/api-explorer/capital/latest/get/grants) request. The following example shows a webhook for a grant eligible for grant renewal. **Grant eligible for renewal** ```json { "data": { "balancePlatform": "TestBalancePlatform", "id": "GR00000000000000000000001", "grant": { "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "GO00000000000001", "balances": { "currency": "EUR", "fee": 94406, "principal": 629375, "total": 723781 }, "id": "GR00000000000000000000001", "status": { "code": "Active" }, "renewal": { "eligible": true, "minimumAmount": { "currency": "EUR", "value": 9440625 } } } }, "environment": "test", "timestamp": "2026-01-21T19:57:25.856Z", "type": "balancePlatform.grants.updated" } ``` ## 2. Get financing offers The renewal offer must be at least 150% of the outstanding balance of the prior grant. Available offers are recalculated weekly and expire after seven days. 1. [Get financing offers](/capital/get-grant-offers) for the account holder. You can get either [dynamic](/capital/get-grant-offers/dynamic-offers) or [static](/capital/get-grant-offers/static-offers) offers. 2. In your user interface, present the offers that meet the `renewal.minimumAmount` from the webhook. ## 3. Present the user with the new Terms of Service After the user selects a renewal offer, the `receiveGrants` capability is disallowed until the Terms of Service are accepted again. For grant renewal, underwriting follows specific credit assessment rules to determine the new repayment percentage, fee, and maximum amount. The new terms can differ from the prior grant. The user must re-accept the Terms of Service before the subsequent grant can be disbursed. 1. [Generate a Terms of Service document](/capital/terms-of-service). 2. In your user interface, present the Terms of Service for acceptance. ## 4. Configure a subsequent grant To configure a subsequent grant: 1. Make a POST [/grants](https://docs.adyen.com/api-explorer/capital/latest/post/grants) request, specifying the following parameters: | Parameter | Type | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [counterparty.balanceAccountId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-counterparty-balanceAccountId) | String | | The unique 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. 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). | | [counterparty.transferInstrumentId](https://docs.adyen.com/api-explorer/capital/latest/post/grants#request-counterparty-transferInstrumentId) | String | | The unique 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) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique 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) | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the grant offer that has been selected by the user. | | `renewsGrantId` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the prior grant to renew. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/required.svg?decoding=auto\&fetchpriority=auto) Required\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/capital-legend/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Conditionally required The following example shows how to configure a grant to renew a prior grant. **Disburse a subsequent 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 '{ "counterparty": { "balanceAccountId": "BA00000000000000000000001" }, "grantAccountId": "CG00000000000000000000001", "grantOfferId": "0000000000000002", "renewsGrantId": "GR00000000000000000000001" }' ``` 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 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 that contains 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. | | `renewsGrantId` | The unique identifier of the prior grant that the current grant renews. | **Subsequent grant requested** ```json { "grantAccountId": "CG00000000000000000000001", "counterparty": { "accountHolderId": "AH00000000000000000000001", "balanceAccountId": "BA00000000000000000000001" }, "grantOfferId": "0000000000000002", "id": "GR00000000000000000000002", "status": { "code": "Requested" }, "balances": { "principal": 0, "fee": 0, "total": 0, "currency": "EUR" }, "renewsGrantId": "GR00000000000000000000001" } ``` Adyen processes POST [/grants](https://docs.adyen.com/api-explorer/capital/latest/post/grants) requests asynchronously. You 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. ## 5. Get updates Adyen sends 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 Adyen configures the subsequent grant, you 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": "GO00000000000002", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000002", "status": { "code": "Requested" }, "renewsGrantId": "GR00000000000000000000001" } }, "environment": "test", "timestamp": "2026-01-21T19:56:42.107Z", "type": "balancePlatform.grants.created" } ``` ### Tab: Transfer received After Adyen configures the subsequent grant, you 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": "GR00000000000000000000002", "description": "GR00000000000000000000002", "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 Adyen receives the grant payout request, you 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": "GR00000000000000000000002", "referenceForBeneficiary": "GR00000000000000000000002", "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 Adyen authorizes the grant payout request, you 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": "GR00000000000000000000002", "referenceForBeneficiary": "GR00000000000000000000002", "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 Adyen pays out the funds to the receiving balance account or payment instrument, you 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": "GR00000000000000000000002", "instructedAmount": { "currency": "EUR", "value": -1850000 }, "reference": "GR00000000000000000000001", "referenceForBeneficiary": "GR00000000000000000000002", "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 subsequent grant, you 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": "GO00000000000002", "balances": { "currency": "EUR", "fee": 0, "principal": 0, "total": 0 }, "id": "GR00000000000000000000002", "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)