Get started with a Lite account
Last updated: November 13, 2024
This guide demonstrates the complete process from onboarding a sub-entity to processing payments on its behalf. Select Sole trader or Company below to see the specific steps for each.
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(s), 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.
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 due diligence 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
- Keep up to date with webhook notifications
You don't need to provide all of the sub-entity information required for due diligence checks upfront. You can supply a minimum amount of information, and submit additional information at a later point.
However, our checks (CSS, PEP, KYC and KYB) 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.
Use
post
/accounts/entities to create a sub-entity representing Daniel’s Donuts.
Information
You will only be able to specify the individual.registered_address.country and profile.mccs to those that were configured for your scope during onboarding.
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 pending. This is because due diligence checks haven't been completed yet.
Note that the sub_entity_created webhook notification will also be sent.
That’s all it takes to create and trigger due diligence checks for a sub-entity!
Once we have conducted our due diligence checks, we will inform you of the outcome via webhook notification. You should expect to receive the vmss_passed / vmss_failed and match_passed / match_failed event types. Both VMSS and Match checks must pass to pass CSS checks successfully. Unless one of our legal_name fail triggers is used for testing purposes, due diligence will always pass in Sandbox.
For Daniel’s Donuts, we receive the pass event types (vmss_passed and match_passed) with the following payload:
If due diligence is passed, we will enable the sub-entity’s payment capability. You should expect to receive the payments_enabled event type.
For Daniel’s Donuts, we receive payments_enabled with the following payload:
Note
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 vmss_failed and / or match_failed notification, this will be followed by payments_disabled webhook notification.
Now that your sub-entity's payments capabilities have been enabled, you’re ready to start using it. Our API enables you to process payments on behalf of a sub-entity by specifying its ID in the amount_allocations[].id field when using
post
/payments.We’ll use the Daniel’s Donuts id from step 1 to process a payment for £10 on its behalf. An id will start with ent and looks like ent_wxglze3wwywujg4nna5fb7ldli.
Information
Funds will be routed and held in your platform’s currency accounts as per the preferences agreed for your platform during onboarding. In this example, all payments are being routed to GBP.
Use the approved field to check whether 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.com fees) will be routed to and held in Desserts Delivered’s GBP currency account.
All funds will be settled to your platform’s designated bank account(s) as per the frequency agreed during onboarding.
The distribution of funds to your sub-entities and collection of fees for your platform are both done outside of our solution.
To understand more about routing and holding funds, you can optionally generate a Balance Report to retrieve the available closing balance of your currency account(s) on a daily basis. If you’d like to reconcile transactions for each sub-entity, you can generate a daily Financial Actions by Payout ID Report to view a breakdown.
That's it! You've successfully completed your first payment.