Skip to content

Quick start (full)

Beta

Last updated: December 21, 2022

This guide demonstrates the full process, from onboarding a sub-entity to processing payments on its behalf.

Before you begin

Check you've completed the following steps before starting your integration.

  • Your account is able to onboard sub-entities.
  • You have your client_id and client_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 and KYB) unless otherwise agreed with you during your own onboarding.

Step 1: Onboard your sub-entities

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
  • Upload identity documentation
  • Keep up to date with webhook notifications

Step 1a: Onboard a sub-entity

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.

Request

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.

1
{
2
  "reference":"0123456",
3
  "contact_details":{
4
    "phone":{
5
      "number":"2345678910"
6
    },
7
    "email_addresses": {
8
      "primary": "hello@thecakeshop.com"
9
    }
10
  },
11
  "profile":{
12
    "urls":[
13
      "https://www.daniels-donuts.com"
14
    ],
15
    "mccs":[
16
      5814
17
    ]
18
  },
19
  "individual":{
20
    "first_name":"Daniel",
21
    "last_name":"Yubi",
22
    "trading_name":"Daniel's Donuts",
23
    "national_tax_id":"1234567",
24
    "registered_address":{
25
      "address_line1":"90 Tottenham Court Road",
26
      "city":"London",
27
      "zip":"W1T4TJ",
28
      "country":"GB"
29
    }
30
  }
31
}

Information

  • You will only be able to specify the individual.registered_address.country, profile.mccs and profile.default_holding_currency to those that were configured for your scope during onboarding.
  • Note that profile.default_holding_currency of GBP means that payments processing on behalf of Daniel’s Donuts would be routed and held in the Platform GBP currency account.

Response

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.

1
{
2
  "id":"ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
3
  "reference":"0123456",
4
  "status": "requirements_due",
5
  "capabilities":{
6
    "payments":{
7
      "available":true,
8
      "enabled":false
9
    },
10
    "payouts":{
11
      "available":true,
12
      "enabled":false
13
    }
14
  },
15
 "requirements_due": [
16
    {
17
       "field": "individual.identification.document",
18
       "reason": "required"
19
    }
20
  ],
21
  "_links":{
22
    "self":{
23
      "href":"https://api.sandbox.checkout.com/accounts/entities/ent_vv2jjkuf2gzj5tcw2x7ptua7zy"
24
    }
25
  }
26
}

Note that the sub_entity_created webhook notification will also be sent.

That’s all it takes to create a sub-entity!

Step 1b: Upload identity documentation

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.

Step 1c: Handle due diligence result and capability changes

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:

1
{
2
  "id": "evt_htielsmgcwgejgqaunl4yb2pou",
3
  "type": "full_dd_passed",
4
  "version": "1.0.0",
5
  "created_on": "2020-08-20T15:24:13.8431084Z",
6
  "data": {
7
    "sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
8
    "reference": "123456789101112",
9
    "legal_name": "Daniel Yubi"
10
  },
11
  "_links": {
12
    "self": {
13
      "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
14
    }
15
  }
16
}

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:

1
{
2
  "id": "evt_htielsmgcwgejgqaunl4yb2pou",
3
  "type": "payments_enabled",
4
  "version": "1.0.0",
5
  "created_on": "2020-08-20T15:24:13.8431084Z",
6
  "data": {
7
    "sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
8
    "reference": "123456789101112",
9
    "legal_name": "Daniel Yubi"
10
  },
11
  "_links": {
12
    "self": {
13
      "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
14
    }
15
  }
16
}

1
{
2
  "id": "evt_htielsmgcwgejgqaunl4yb2pou",
3
  "type": "payouts_enabled",
4
  "version": "1.0.0",
5
  "created_on": "2020-08-20T15:24:13.8431084Z",
6
  "data": {
7
    "sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
8
    "reference": "123456789101112",
9
    "legal_name": "Daniel Yubi"
10
  },
11
  "_links": {
12
    "self": {
13
      "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
14
    }
15
  }
16
}

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.

Step 2: Accept payments

Now that your capabilities have been enabled, you’re ready to start using them. Our Unified Payments API enables you to process payments on behalf of a sub-entity by specifying its id in the marketplace 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.

Collecting platform fees

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.

Request

1
{
2
  "amount": 1000,
3
  "currency": "GBP",
4
  "reference": "ORD-5023",
5
  "description": "Three chocolate donuts",
6
  "capture": true,
7
  "source": {
8
    "type": "card",
9
    "number": "4242424242424242",
10
    "expiry_month": 11,
11
    "expiry_year": 2024,
12
    "cvv": "100"
13
  },
14
  "processing_channel_id": "pc_yghfzjebuiwelerjsk3atodrey",
15
  "amount_allocations": [
16
    {
17
      "id": "ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
18
      "amount": 1000,
19
      "reference": "ORD-5023",
20
      "commission": {
21
        "amount": 200
22
      }
23
    }
24
  ]
25
}

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.

Response

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.

1
{
2
  "id":"pay_upzwlsfvsgwetnqzsr7ex7ehjm",
3
  "action_id":"act_e3s33ooalqzuhjukxhvs46qnbi",
4
  "amount":1000,
5
  "currency":"GBP",
6
  "approved":true,
7
  "status":"Authorized",
8
  "auth_code":"523540",
9
  "response_code":"10000",
10
  "response_summary":"Approved",
11
  "balances":{
12
    "total_authorized":1000,
13
    "total_voided":0,
14
    "available_to_void":1000,
15
    "total_captured":0,
16
    "available_to_capture":1000,
17
    "total_refunded":0,
18
    "available_to_refund":0
19
  },
20
  "risk":{
21
    "flagged":false
22
  },
23
  "source":{
24
    "id":"src_mbe6cmlirw6u7ou7i47sumvree",
25
    "type":"card",
26
    "expiry_month":11,
27
    "expiry_year":2024,
28
    "scheme":"Visa",
29
    "last4":"4242",
30
    "fingerprint":"0418BC9FAEA9AC9630A54573D5ADEDB324F0255CE620CBA8CA62598726F3E77C",
31
    "bin":"424242",
32
    "card_type":"CREDIT",
33
    "card_category":"CONSUMER",
34
    "issuer":"JPMORGAN CHASE BANK NA",
35
    "issuer_country":"US",
36
    "product_id":"A",
37
    "product_type":"Visa Traditional",
38
    "cvv_check":"Y",
39
    "payment_account_reference":"V001442883304956196"
40
  },
41
  "processed_on":"2021-03-29T15:42:18.5005983Z",
42
  "reference":"ORD-5023",
43
  "scheme_id":"662371971743145",
44
  "processing":{
45
    "acquirer_transaction_id":"282527877143942840484",
46
    "retrieval_reference_number":"535323190665"
47
  },
48
  "expires_on":"2021-04-28T15:42:18.5005983Z",
49
  "_links":{
50
    "self":{
51
      "href":"https://api.sandbox.checkout.com/payments/pay_upzwlsfvsgwetnqzsr7ex7ehjm"
52
    },
53
    "actions":{
54
      "href":"https://api.sandbox.checkout.com/payments/pay_upzwlsfvsgwetnqzsr7ex7ehjm/actions"
55
    },
56
    "capture":{
57
      "href":"https://api.sandbox.checkout.com/payments/pay_upzwlsfvsgwetnqzsr7ex7ehjm/captures"
58
    },
59
    "void":{
60
      "href":"https://api.sandbox.checkout.com/payments/pay_upzwlsfvsgwetnqzsr7ex7ehjm/voids"
61
    }
62
  }
63
}

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

Step 3: Scheduled payouts

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

Step 3a: Retrieve currency account balance

You can view your sub-entity balances using the Dashboard or API.

Step 3b: Create sub-entity payment instrument

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.

Request

Tip

Grab the file_id in the same way you did for the identification document.

1
{
2
  "label":"Daniel's Donuts Barclays",
3
  "type":"bank_account",
4
  "account_number":"12345678",
5
  "bank_code":"050389",
6
  "currency":"GBP",
7
  "country":"GB",
8
  "account_holder":{
9
    "company_name":"Daniel's Donuts",
10
    "billing_address":{
11
      "address_line1":"90 Tottenham Court Road",
12
      "city":"London",
13
      "state":"London",
14
      "zip":"W1T 4TJ",
15
      "country":"GB"
16
    }
17
  }
18
}

We will attempt to create the payment instrument asynchronously (behind the scenes), and inform you of the result via the payment_instrument_created and payment_instrument_error webhook notifications.

For Daniel’s Donuts, we receive the payment_instrument_created notification – this contains data.payment_instrument_id, which we’ll need to make our payout to Daniel’s Donuts later:

1
{
2
  "id": "evt_htielsmgcwgejgqaunl4yb2pou",
3
  "type": "payment_instrument_created",
4
  "version": "1.0.0",
5
  "created_on": "2020-08-20T15:24:13.8431084Z",
6
  "data": {
7
    "sub_entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
8
    "payment_instrument_id": "src_33z5qxrwp2bulj4volyqvarhyq",
9
    "label": "Daniel's Donuts Barclays"
10
  },
11
  "_links": {
12
    "self": {
13
      "href": "https://api.sandbox.checkout.com/workflows/events/evt_htielsmgcwgejgqaunl4yb2pou"
14
    }
15
  }
16
}

If successful, we will automatically make the association between this payment instrument and its sub-entity. You can see this association and alternatively retrieve the payment instrument id by using

get

/accounts/entities/{id} again:

1
{
2
  "instruments": [
3
    {
4
      "id": "src_33z5qxrwp2bulj4volyqvarhyq",
5
      "label": "Daniel's Donuts Barclays"
6
    }
7
  ]
8
}

Step 3c: Scheduled payouts

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 see the results of the payouts, use our reconciliation reporting solution.

Tip

That's it! You've successfully completed your first payment flow.

FAQs

On this page

Before you begin
Step 1: Onboard your sub-entities
Step 2: Accept payments
Step 3: Scheduled payouts
FAQs