Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Offer grants

Learn how to use Adyen Capital to build an embedded financing offering via API.

Request an invite

Interested to learn more about Adyen Capital? Fill out this form to let us know.

This feature is currently available on an invite only basis. Some of the APIs, documentation, and processes may change as the feature evolves.

Adyen Capital allows you to build an embedded financing offering for your eligible users for their operational needs. With Adyen Capital, you can allow them to get business financing from Adyen that is completely integrated into your UI by using our APIs. We assess risks upfront and proactively create offers for your users. This allows your users to quickly get funds paid out to their balance account or transfer instrument, without the need for an additional application process.

Users repay daily based on a fixed percentage of their processed volume through Adyen. This way, they only repay as they earn and repayments do not impede their cash flow. In addition, users pay one transparent fixed fee — no interest and no hidden costs.

Account structure

Before you start building the integration, you need to understand the account structure of Adyen Capital as well as the general account structure of Adyen for Platforms.

Grant

We call a unit of business financing a grant. This is conceptually similar to the funds paid out to the user and the conditions they need to meet to repay the funds.

Grant account

For your platform, we create a new type of account — grant account. This account doesn't hold any funds and allows to track the total amount of outstanding receivables that Adyen has towards the users on your platform. You can view the total of all outstanding grants on your platform on your grant account.

We assign one currency per grant account. If you need to offer grants in multiple currencies, you will need multiple grant accounts — one for each currency.

For example, if Adyen pays out five grants worth 10.000 EUR with a fee of 1.000 EUR each to your users, then this account will have a total of 55.000 EUR.

The grant account has an ID starting with CG, for example, CG00000000000000000000001, where CG stands for Capital Grant Account.

Grant reference

For your users, we create a grant reference that has a one-to-one relationship with the grant. This means that every time a new grant is paid out, a new grant reference is created.

The grant reference tracks the total balance, the principal balance, and the fee balance to keep a record of the outstanding grant. The grant reference has an active status until the grant is fully repaid. Once the grant is fully repaid, the grant reference is closed—status closed.

For example, if Adyen pays out a grant worth 10.000 EUR with a fee of 1.000 EUR to your user, then this reference will have a total of -11.000 EUR. The negative balance decreases as the user repays the grant until the balance is 0 EUR.

The grant reference has an ID starting with GR, for example, GR00000000000000000000001.

Grant offers

Adyen does a proactive risk assessment of your user based on the user's payments data. This assessment results in a maximum of three grant offers that can be displayed to the user. When the user selects an offer and the relevant capabilities have been activated, the grant will be paid out.

Offers are only generated for the users that have met our eligibility criteria. To learn more about the eligibility criteria, reach out to your Adyen contact.

Payout

When the user selects a grant offer, you or the user can configure the grant to be paid out to the:

  • Balance account linked to their account holder.
  • Transfer instrument that belongs to the same legal entity as their account holder.

If you're paying out to a balance account, the funds stay within the platform. This might be beneficial if you're using Adyen Business Accounts.

In both cases, the funds are booked as incoming transfers to the balance account. In case of a payout to a transfer instrument, an outgoing transfer is automatically booked.

Repayment

To ensure consistent repayment of the grant, we reserve a fixed percentage from each incoming capture of the user. This reservation is deducted daily from net captured volume — captures minus refunds and chargebacks. In case the capture is refunded or charged back, we release the reservation on the day this refund or chargeback is booked.

At the end of the day, we trigger an outgoing transfer from the user's balance account for the entire reserved amount on the given day. This constitutes the real money repayment.

To keep track of the repayments, we calculate a threshold amount — the amount against which we monitor the repayment. If the total 30-day repayment drops below this threshold, we may take additional action to make sure that the user repays on time.

In some cases, we set a maximum term at which the user has to repay the entire grant and fee.

Request capabilities

Adyen Capital requires your user's account holder to have the following capabilities:

  • getGrantOffers: The user can get grant offers. After you have requested this capability, we will start checking the user against the eligibility criteria.
  • receiveGrants: The user can receive grants from Adyen. When activated, we check whether the account holder has signed the Terms of Service.

After the capability has been activated you receive a balancePlatform.accountHolder.updated notification.

To learn how to request a capability for an account holder, see Manage account holders.

Get available grant offers

To get the grant offers available for your user, make a GET /grantOffers request with the accountHolderId as a query parameter:

Query parameter Required Description
accountHolderId -white_check_mark- The unique identifier of the receiving account holder.
Get grants available for the account holder
curl https://balanceplatform-api-test.adyen.com/btl/v1/grantOffers?accountHolderId=AH00000000000000000000001 \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-X GET \
-d ''

The response contains the following parameters:

Parameter Description
accountHolderId The unique identifier of the receiving account holder.
grantOffers An object containing the details of the available grant offer(s).
grantOffers.id The unique identifier of the grant offer.
grantOffers.contractType The legal type of the grant offer. Possible values: loan, cashAdvance.
grantOffers.startsAt The starting date of the offer validity period.
grantOffers.expiresAt The expiring date of the offer validity period.
grantOffers.repayment An object containing the details of the repayment configuration.
grantOffers.repayment.
basisPoints
The repayment that is deducted daily from incoming net volume, in basis points.
grantOffers.repayment.
threshold
An object containing the details of the 30-day repayment threshold.
grantOffers.term.
estimatedDays
The estimated term for repaying the grant, in days.
grantOffers.term.
maximumDays
The maximum term for repaying the grant, in days. Only applies when contractType is loan.
grantOffers.fee An object containing the fee currency and value, in minor units.
grantOffers.amount An object containing the amount of the grant, in minor units.

The following example offer is a grant of 10.000 EUR with a fee of 1.200 EUR. The repayment rate is 14 percent with a 90-day expected term and a 135-day maximum term. The threshold amount for the 30-day repayment is 2.489 EUR.

Grant offer(s) available for the account holder
{
    "accountHolderId": "AH00000000000000000000001",
    "grantOffers": [
        {
            "id": "0000000000000001",
            "contractType": "loan",
            "startsAt": "2022-06-16T08:04:27Z",
            "expiresAt": "2022-07-16T08:04:27Z",
            "repayment": {
                "basisPoints": 1400,
                "threshold": {
                    "amount": {
                        "currency": "EUR",
                        "value": 248889
                    }
                },
                "term": {
                    "estimatedDays": 90,
                    "maximumDays": 135
                }
            },
            "fee": {
                "amount" : {
                    "value" : 120000,
                    "currency" : "EUR"
                }
            },
            "amount": {
                "value": 1000000,
                "currency": "EUR"
            }
        }
    ]
}

Sign Terms of Service

The user must sign the Terms of Service (ToS) before Adyen pays out the grant. Signing the ToS will activate the receiveGrants capability. It is up to you to have the user sign the ToS either before or after receiving the grant offers.

Request a grant

After the user selects the grant and signs the Terms of Service, make a POST /grants request to:

  • Create a new grant reference.
  • Pay out the grant.

Include the following parameters:

Parameter Required Description
counterparty.accountHolderId -white_check_mark- The unique identifier of the receiving account holder.
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 -white_check_mark- The identifier of the grant account. Reach out to your Adyen contact to get this value.
grantOfferId -white_check_mark- 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.

Pay out the grant to the balance account
curl https://balanceplatform-api-test.adyen.com/btl/v1/grants \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-X POST \
-d '{
  "grantAccountId": "CG00000000000000000000001",
  "grantOfferId": "0000000000000001",
  "counterparty": {
    "accountHolderId": "AH00000000000000000000001",
    "balanceAccountId": "BA00000000000000000000001"
  }
}'

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.
Response
{
    "id": "GR00000000000000000000001",
    "grantAccountId": "CG00000000000000000000001",
    "grantOfferId": "0000000000000001",
    "counterparty": {
        "accountHolderId": "AH00000000000000000000001",
        "balanceAccountId": "BA00000000000000000000001"
    },
    "amount": {
        "currency": "EUR",
        "value": 1000000
    },
    "fee" : {
        "amount" : {
            "value" : 120000,
            "currency" : "EUR"
        }
    },
    "repayment": {
        "basisPoints": 1400,
    },
    "status": "approved"
}

Requests using POST /grants are processed asynchronously. You'll receive a response to your API request, but you must wait for the webhook notification to know the final result of a request.

Get updates

Adyen sends the following webhook notifications to your server:

  1. balancePlatform.grants.created: the grant has been configured.
  2. balancePlatform.transaction.created: the grant has been paid out to the balance account or the payment instrument.

To keep track of notifications, make sure that your server can receive and accept webhooks.

Grant configured

After the requested grant has been configured on the Adyen side, you will receive a balancePlatform.grants.created notification.

Grant configured notification
{
    "data": {
        "id": "GR00000000000000000000001",
        "grantAccountId": "CG00000000000000000000001",
        "grantOfferId": "0000000000000001",
        "creationDate:": "2022-06-09T17:09:52+02:00",
        "counterparty": {
            "accountHolderId:": "AH00000000000000000000001",
            "balanceAccountId": "BA00000000000000000000001"
        },
        "amount": {
            "currency": "EUR",
            "value": 1000000
        },
        "fee": {
            "amount": {
                "currency": "EUR",
                "value": 120000
            }
        },
        "repayment": {
            "basisPoints": 1400
        },
        "status": "active",
        "sequenceNumber": 1
    },
    "environment": "test",
    "type": "balancePlatform.grants.created"
}

Grant paid out

After the grant has been paid out, you will receive a balancePlatform.transaction.created notification.

Get balances

You can get the balances of a single grant or all grants on your platform's grant account.

Get balances of one grant

To get the balance of a single grant:

  1. Make a GET /grants/{id} request and specify the following parameter in the path:

    Path parameter Description
    id The unique identifier of the grant reference received when requesting a grant.
    Get the balances of a one grant
    curl https://balanceplatform-api-test.adyen.com/bcl/v1/grants/GR00000000000000000000001 \
    -H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
    -H "content-type: application/json" \
    -X GET \
    -d ''

    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, in basis points.
    balances An object containing the details of the existing grant.
    status The status of the grant.
    Response
    {
        "id": "GR00000000000000000000001",
        "grantAccountId": "CG00000000000000000000001",
        "grantOfferId": "00000000001",
        "counterparty": {
            "accountHolderId": "AH00000000000000000000001",
            "balanceAccountId": "BA00000000000000000000001"
        },
        "amount": {
            "currency": "EUR",
            "value": 1000000
        },
        "fee" : {
            "amount" : {
                "value" : 120000,
                "currency" : "EUR"
            }
        },
        "repayment": {
            "basisPoints": 1400
        },
        "balances": {
            "principal": 1000000,
            "fee": 120000,
            "total": 1120000,
            "currency": "EUR"
        },
        "status": "approved"
    }

Get balances of all grants

To check the balances of all grants on your platform's grant account:

  1. Make a GET /grantAccounts/{id} request and specify the following parameter in the path:

    Path parameter Description
    id The unique identifier of the grant account received from your Adyen contact.
    Get the balances of all grants
    curl https://balanceplatform-api-test.adyen.com/bcl/v1/grantAccounts/CG00000000000000000000001 \
    -H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
    -H "content-type: application/json" \
    -X GET \
    -d ''

    The response contains the following parameters:

    Parameter Description
    id The unique identifier of the grant account.
    balances An object containing the details of all the existing grant(s) on your platform's grant account.
    limit An object containing the details about the maximum allowed total amount for all grants on this grant account.
    Response
    {
        "id": "CG00000000000000000000001",
        "balances": {
            "principal": 1000000,
            "fee": 120000,
            "total": 1120000,
            "currency": "EUR"
        },
        "limit" : {
            "amount" : {
                "value" : 10000000,
                "currency" : "EUR"
            }
        }
    }