Get started with a Full account
Last updated: March 5, 2025
This guide demonstrates the full process, from onboarding a sub-entity to processing payments on its behalf.
Check you've completed the following steps before starting your integration.
- Your account is able to onboard sub-entities.
- You have your
client_idandclient_secret, so you can generate access tokens with the required scopes. See our authentication workflow for more information. - You have your processing channel ID, currency account and payment instrument IDs which will be required throughout the process.
- You have configured your webhooks and subscribed to the relevant events through our Workflow API.
- You are familiar with our account structure.
Note
Your sub-entities will undergo full onboarding checks (CSS, PEP, KYC, KYB, and bank account verification) unless otherwise agreed with you during your own onboarding.
Vendors, retailers and service providers on your platform are represented by sub-entities in our solution. A sub-entity is used to collect the information we require to perform verification checks, as well as capture certain preferences.
In this step we’re going to walk through the complete onboarding of a sub-entity:
- Onboard with the minimum required information
- Upload identity documentation
- Keep up to date with webhook notifications
You don't need to provide all of the sub-entity information required for verification checks upfront. You can supply a minimum amount of information, and submit additional information at a later point.
However, our checks (CSS, PEP, KYC, KYB, and bank account verification) will only be triggered once we have all of the information required to conduct them.
Note
Your sub-entity will not be able to process payments or receive payouts until it has passed these checks.
Read more on our onboarding page.
We will use the example of Daniel’s Donuts, a donut seller (who is a sole proprietor) on our fictional platform, Desserts Delivered. We will provide the minimum required fields for Daniel’s Donuts to start its onboarding!
Use
post
/accounts/entities.
Information
- You will only be able to specify the
individual.registered_address.country,profile.mccsandprofile.default_holding_currencyto those that were configured for your scope during onboarding. - Note that
profile.default_holding_currencyofGBPmeans that payments processing on behalf of Daniel’s Donuts would be routed and held in the platform GBP currency account.
A successful response will include a unique sub-entity id, which you should store for future requests. Additionally, the response has the capabilities object, which shows you whether the sub-entity’s capabilities are enabled or not. Capabilities only get enabled once specific due diligence checks have been run and passed.
You will also notice there is a status field set to requirements_due. This is because we still require more information before we can conduct due diligence checks – in this case, it is the identification document.
Note that the sub_entity_created webhook notification will also be sent.
That’s all it takes to create a sub-entity!
Use the id returned to upload an identification document. Find out how to do this using our Files API.
You then need to update the sub-entity with this identification document attached, so we trigger due diligence checks.
Read more about how to do this on our onboarding page.
Once we have conducted our due diligence checks, we will inform you of the outcome via webhook notification. You should expect to receive the full_dd_passed and full_dd_failed event types. Unless one of our legal_name fail triggers is used for simulation, due diligence will always pass in Sandbox.
For Daniel’s Donuts, we receive the full_dd_passed with the following payload:
If due diligence is passed, we will enable the sub-entity’s payment and payout capabilities. You should expect to receive the payments_enabled and payouts_enabled event types.
For Daniel’s Donuts, we receive the payments_enabled and payouts_enabled with the following payloads:
Information
We will re-trigger due diligence checks if any of the required information is later updated. If any subsequent checks fail and you receive the full_dd_failed notification, which will be followed by payments_disabled and payouts_disabled.
Now that your capabilities have been enabled, you’re ready to start using them. Our API enables you to process payments on behalf of a sub-entity by specifying its ID in the amount_allocations[] object when using
post
/payments.We’ll use the Daniel’s Donuts id from step 1 to process a payment for £10 on its behalf.
Information
Funds will be routed and held in your sub-entity's currency account as per the preferences agreed for your platform during onboarding. In this example all payments are being routed to GBP.
When requesting a payment on behalf of your sub-entity, you can request a commission.
There are three ways to charge commission on your sub-entities' payments:
- Fixed commission amount in minor currency units.
- Variable commission (in percentage).
- Compound commission (both a fixed and variable commission together).
In this example, we charge a fixed commission of £2. Read our payments page for more information about charging commission.
Information
processing_channel_id corresponds to a specific merchant category code (MCC) that you are setup to process payments for. Your processing channel IDs will be provided to you after we have completed your setup.
Use the approved field to check whether or not the authorization was successful ("approved": true). The balances object provides an overview of the payment’s balances, which helps you determine the amount that can be used for each subsequent action on the payment.
That’s it! £10 has been processed on behalf of Daniel's Donuts and the funds (minus Checkout fees) will be routed to and held in Desserts Delivered’s GBP currency account
Now that we’ve successfully processed a payment on behalf of our sub-entity, we have funds available to be paid out to our sub-entities.
In this step we’re going to walk through the steps that will enable us to do this:
- Retrieve currency account balance
- Store sub-entity bank account details
You can view your sub-entity balances using the Dashboard or API.
A payment instrument is a set of bank account details securely stored in our vault. You will need to create a payment instrument for your sub-entity so that it can later be used as a destination when making payouts directly to them.
Note
Your platform's bank account is also represented as a payment instrument, and will be used as the destination when making payouts to yourself to collect your Platform fees. Your Platform payment instrument ID(s) will be provided to you after we have completed your setup.
We will create a payment instrument representing Daniel’s Donuts Barclays bank account details in this step. Use
post
/accounts/entities/{id}/payment-instruments to create a sub-entity payment instrument.Information
Grab the file_id in the same way you did for the identification document.
The response contain's the payment instrument ID. You must use the ID when you perform a payout to the sub-entity.
During your onboarding, you will have selected a schedule for a sub-entity's funds to be paid out to them – daily, once a week or once a month. If there’s money in the account, and the bank account has been verified, the payouts will begin as per the schedule.
To see the results of the payouts, use our reconciliation reporting solution.
That's it! You've successfully completed your first payment flow.
A rolling reserve is a percentage of your gross transaction amount that we hold as a reserve to protect your account from financial losses due to unexpected risk events. For example, a sub-merchant bankruptcy or fraud.
These funds are held over a pre-agreed amount of time referred to as the holding duration.
At the end of the holding duration, the amount held from each transaction is released to the available balance. This amount will then be paid out as part of the next scheduled payout or payout instruction. A sub-entity’s rolling reserve balance is tracked in the collateral balances of the corresponding currency account.
A rolling reserve rule is a policy you can configure with Checkout.com. The rule typically has a reserve percentage and a holding duration.
Information
Only a single rolling reserve rule can be active at any point. Upcoming rules can be added and updated, as required. If a rule is active, it cannot be changed but can be overridden by a new rule.
If the holding duration is updated, the new holding duration will immediately apply to any existing collateral balance.
For example, if the new holding duration is shorter than the previous holding duration, there will be a bulk release of any collateral funds that have been held longer than the period of time set by the new rule.
You can use the Dashboard or API to configure and update reserve rules.
A reserve rule becomes active and starts processing payments from the date specified in the valid_from field.
post
https://api.checkout.com/accounts/entities/{id}/reserve-rules
A reserve rule can only be updated if it has never been active. This means that the valid_from date is in the future and as a result, no payments have been processed.
post
https://api.checkout.com/accounts/entities/{id}/reserve-rules/{id}
To get details about a specific reserve rule, see our API reference.