Capital icon

Disburse a grant

Learn how to make a request for a grant and disburse the funds to your user's account.

View source

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 that supports Capital.
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:
  • Balance Platform Capital Configuration role
  • Balance Platform Capital Grant Initiation role
Capabilities Make sure that your user has the following capabilities:
  • getGrantOffers
  • receiveGrants
Webhooks Subscribe to the following webhooks:
Limitations
  • Your user must operate in one of the supported countries/regions.
  • 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:

1. Configure a grant

To renew an active grant, see Renew a grant.

To configure a grant:

  1. Make a POST /grants request, specifying the following parameters:

    Parameter Type Required Description
    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.
    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 String Required The unique identifier of the grant account. Reach out to your Adyen contact to get this value.
    grantOfferId String Required The unique identifier of the grant offer that has been selected by the user.

    This is the required icon. Required
    This is the conditionally required icon. Conditionally required

    The following example shows how to disburse a grant to the specified balance account.

  2. In the response, note the following parameters:

    Parameter Description
    id The unique identifier of the grant.
    grantAccountId The identifier of the grant account used to account for the grant.
    grantOfferId The unique identifier for the related grant offer, which determines the grant conditions.
    counterparty An object that contains the details of the receiving account holder.
    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 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 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.

Next steps

Get grant details

Learn how to get information about all grants in your balance platform.
Manage disbursements

Learn how to get and update configurations of a disbursement.