Skip to content
Platforms / Quick start (lite)

Quick start (lite) Early access

Last updated: 14th July 2022

This guide demonstrates the complete process from onboarding a sub-entity to processing payments on its behalf. Select Individual or Company below to see the specific steps for each.

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(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.

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

    Step 1a: Onboard a sub-entity

    We will trigger our checks only when we have all of the information required to conduct them. If our due diligence checks pass, payment capabilities for this sub-entity will be enabled.

    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.

    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
    {
        "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 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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    {
      "id":"ent_vv2jjkuf2gzj5tcw2x7ptua7zy",
      "reference":"0123456",
      "status": "pending",
      "capabilities":{
        "payments":{
          "enabled":false
        },
        "payouts":{
          "enabled":false
        }
      },
      "requirements_due": [],
      "_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 and trigger due diligence checks for a sub-entity!

    Step 1b: 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 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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    {
      "id": "evt_htielsmgcwgejgqaunl4yb2pou",
      "type": "vmss_passed",
      "version": "1.0.0",
      "created_on": "2020-08-20T15:24:13.8431084Z",
      "data": {
        "sub_entity_id": "ent_ahlzzbn2lepib3jigq4tbj7rju",
        "reference": "123456",
        "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 capability. You should expect to receive the payments_enabled event type.

    For Daniel’s Donuts, we receive payments_enabled with the following payload:

    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_ahlzzbn2lepib3jigq4tbj7rju",
        "reference": "123456",
        "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 vmss_failed and / or match_failed notification, this will be followed by payments_disabled webhook notification.

    Step 2: Accept payments

      Now that your sub-entity's payments capabilities have been enabled, you’re ready to start using it. Our Unified Payments API enables you to process payments on behalf of a sub-entity by specifying its id in the marketplace.sub_entity_id field when using post /payments.

      We’ll use Daniel’s Donut's id from step 1 to process a payment for £10 on its behalf. An id will start with ent and looks like ent_wxglze3wwywujg4nna5fb7ldli.

      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.

      Request

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      {
        "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_entity_id":"ent_vv2jjkuf2gzj5tcw2x7ptua7zy"
        }
      }

      Response

      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.

      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.

      Client settlements

      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.

      If you wish to understand more about the routing and holding of funds, you can optionally 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 may process daily financial actions reports to retrieve this breakdown.

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

      FAQs

      Capabilities are enabled once due diligence checks have been completed. If you haven't received a webhook notification – either {check}_passed or {check}_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.

      On this page

      Before you begin
      Step 1: Onboard your sub-entities
      Step 2: Accept payments
      Client settlements
      FAQs