Skip to content
Platforms / Quick start (full)

Quick start (full) Early access

Last updated: 14th July 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.

Unless otherwise agreed during your onboarding, your sub-entities will undergo full onboarding (CSS, PEP, KYC and KYB checks). The payments and payouts capabilities will be enabled if the checks are passed.

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

    To provide greater flexibility, we don’t need you to provide all of the data required for due diligence checks upfront. You can onboard a sub-entity with the minimum required information and then enrich it later through updates. We will trigger our checks only when we have all of the information required to conduct them. If our due diligence checks pass, payment and payout capabilities for this sub-entity will be enabled. Read more about this on our onboarding information 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
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    {
      "reference":"0123456",
      "contact_details":{
        "phone":{
          "number":"2345678910"
        }
      },
      "profile":{
        "urls":[
          "https://www.daniels-donuts.com"
        ],
        "mccs":[
          5814
        ]
      },
      "individual":{
        "first_name":"Daniel",
        "last_name":"Yubi",
        "trading_name":"Daniel's Donuts",
        "national_tax_id":"1234567",
        "registered_address":{
          "address_line1":"90 Tottenham Court Road",
          "city":"London",
          "zip":"W1T4TJ",
          "country":"GB"
        }
      }
    }
    • 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
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    {
      "id":"ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
      "reference":"0123456",
      "status": "requirements_due",
      "capabilities":{
        "payments":{
          "enabled":false
        },
        "payouts":{
          "enabled":false
        }
      },
     "requirements_due": [
        {
           "field": "individual.identification.document",
           "reason": "required"
        },
      ],
      "_links":{
        "self":{
          "href":"https://api.sandbox.checkout.com/accounts/entities/ent_vv2jjkuf2gzj5tcw2x7ptua7zy"
        }
      }
    }

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

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

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

    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 Daniel’s Donut's id from step 1 to process a payment for £10 on its behalf.

      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
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      {
        "amount":1000,
        "currency":"GBP",
        "reference":"ORD-5023",
        "description":"Three chocolate donuts",
        "capture":true,
        "source":{
          "type":"card",
          "number":"4242424242424242",
          "expiry_month":11,
          "expiry_year":2024,
          "cvv":"100"
        },
        "processing_channel_id":"pc_yghfzjebuiwelerjsk3atodrey",
        "marketplace": {
          "sub_entities": [
            //Fixed commission amount
            {
              "id": "ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
              "amount": 1000,
              "reference": "ORD-5023",
              "commission": {
                "amount": 200
              }
            },
          ]
        }
      }

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

      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

      We are currently working on exposing real-time currency account balances via API, and hope to offer this functionality soon. In the meantime, you can process balance reports to retrieve the closing available balance of your currency account(s) on a daily basis. If you’d like to reconcile transactions for each sub-entity, you can process daily financial actions reports to retrieve this breakdown.

      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 on-demand payouts directly to them.

      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}/instruments to create a sub-entity payment instrument.

      Request

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

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

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

      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
      3
      4
      5
      6
      7
      8
      9
      10
      11
      {
        "id": "ent_wxglze3wwywujg4nna5fb7ldli",
        ...,
        "instruments": [
          {
            "id": "src_33z5qxrwp2bulj4volyqvarhyq",
            "label": "Daniel's Donuts Barclays"
          }
        ],
        ...,
      }

      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.

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

      FAQs

      Capabilities are enabled once due diligence checks have been completed. If you haven't received a webhook notification – either full_dd_passed or full_dd_failed – it is likely there are outstanding requirements due. Please check our onboarding information page to confirm you have sent all the required information.

      If you have provided all the information, and more than two hours have passed, please allow up to 48 hours to review the sub-entity. In rare cases, we may have to perform checks manually, which can delay our response.

      You will only be able to specify the company.principal_address.country, profile.mccs and profile.default_holding_currency to those that were configured for your scope during onboarding. For example, if your processing scope is only MCC 5311, you cannot change this to 5411. If you’re getting an invalid for scope error, you’ll need change the value(s) to something in your scope, or get in touch with us to update your scope.

      If omitted, profile.default_holding_currency will be set to the default preference specified during your onboarding.

      profile.default_holding_currency is not currently updatable. If you need to change this, please get in touch.

      This means the processing channel you are using is not configured for pay to bank. Please use another one or get in touch to have it enabled on the one you’re using.

      On this page

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