Skip to content

Quick start (lite)

Beta

Last updated: December 21, 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

    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.

    Request

    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": ["https://www.daniels-donuts.com"],
    13
            "mccs": [5814]
    14
        },
    15
        "individual": {
    16
            "first_name": "Daniel",
    17
            "last_name": "Yubi",
    18
            "trading_name": "Daniel's Donuts",
    19
            "national_tax_id": "1234567",
    20
            "registered_address": {
    21
                "address_line1": "90 Tottenham Court Road",
    22
                "city": "London",
    23
                "zip": "W1T4TJ",
    24
                "country": "GB"
    25
            }
    26
        }
    27
    }

    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.

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

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

    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.

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

      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
          }
      20
        ]
      21
      }

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

      Tip

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

      FAQs

      On this page

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