Skip to content

Sub-entity payments

Last updated: 3rd August 2022

Once your sub-entity's payment capabilities have been enabled, you can process payments on behalf of them through our Unified Payments API.

Only Visa and Mastercard payments are currently supported for marketplaces and payment facilitators.

On this page, we explain how to:

We also explain what happens when you refund a split payment.


Link a payment with a sub-entity

When processing a payment on behalf of a sub-entity, you use our Unified Payments API as normal. Create a payment request for the total purchase amount and include all relevant fields using our POST/payments endpoint. See our API reference for all required and optional fields.

However, so we know the payment is on behalf of your sub-entity, you also need to provide the sub-entity's ID.

There are two methods for associating a payment with the correct sub-entity. You can only use one method at a time.

In the marketplace object:

  • Using the sub_entity_id field.
    PayFacs only
  • Using the id field in the sub_entities array.

The sub-entity ID is returned during the onboarding process.


Charge a sub-entity 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

You can only charge commission if you use the marketplace.sub_entities array.


Request a payment for a single sub-entity

Use our POST/payments endpoint to provide the payment details as normal.

You can use either option to request a payment for a single sub-entity – the single marketplace.sub_entity_id string or marketplace.sub_entities array. However, if you would like to charge a commission, you must use the array.

    PayFacs only

    To associate this payment with the correct sub-entity, use the marketplace object and provide the ID in the sub_entity_id field.

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

    processing_channel_id corresponds to a specific MCC that you are set up to process payments for. Your processing channel IDs will be provided to you after we have completed your setup.


    Request a payment for multiple sub-entities

    Marketplaces only

    When a customer uses your platform to buy items from multiple sub-entities, you need to request one payment from the customer, and then split that amount appropriately across the different sub-entities. You may also want to take a commission from each sub-entity for facilitating the transaction on your platform. This is known as a split payment.

    How to split a payment

    Include all relevant fields using our POST/payments endpoint.

    In the marketplace object, include the sub_entities array. This is an array of objects, where each object specifies:

    • The ID of the sub-entity
    • The amount for that sub-entity
    • An optional Platform commission
    • An optional reference to identify the split later

    The sum of all split amounts must be equal to the payment amount.

    Split payments example scenario

    A customer makes a purchase of £100. The split payment contains three splits, which look like:

    1. Sub-entity A: £30 for a shirt
    2. Sub-entity B: £50 for trainers
    3. Sub-entity C: £20 for socks

    If you charge a commission, it will be applied to each split, and cannot exceed the split amount.

    Remember our APIs work in the minor currency unit.

    Request example

    In the example request below, we take the split shown above and demonstrate three ways you can split the payment and specify commission for your platform:

    • Fixed commission amount: Charge the sub-entity in this split a fixed commission amount of £2. This sub-entity would receive £28, and you would receive £2 in your currency account.
    • Variable commission: Charge the sub-entity in this split a fee of 1.5%. This sub-entity would have 1.5% of £50 deducted, so would receive £49.25. You would receive 75p in your currency account.
    • Compound commission: Charge the sub-entity in this split a fee of 1.5%, plus a fixed fee of £2. This sub-entity would have 1.5% of £20 deducted, plus another £2 deducted, so would receive £17.70. You would receive £2.30 in your currency account.
    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
    {
    "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
    },
    "amount": 10000,
    "currency": "GBP",
    "reference": "ORD-5023-4E89",
    "description": "Multi-seller basket",
    "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y",
    "marketplace": {
    "sub_entities": [
    //Fixed commission amount
    {
    "id": "ent_pj6fv2w2wchfedchjjyobb4bni",
    "amount": 3000,
    "reference": "SALE-7627-8389",
    "commission": {
    "amount": 200
    }
    },
    //Commission percentage
    {
    "id": "ent_kjx3tob2sxtl44wb7q7alwdu2m",
    "amount": 5000,
    "reference": "SALE-1729-3782",
    "commission": {
    "percentage": 1.5
    }
    },
    //Fixed commission amount + commission percentage
    {
    "id": "ent_kklowryxmczwyoqe4z7yvcbwvy",
    "amount": 2000,
    "reference": "SALE-2127-9735",
    "commission": {
    "amount": 200,
    "percentage": 1.5,
    }
    }
    ]
    }
    }

    Response examples

    If you receive a successful response, the payment will be automatically associated with the correct sub-entity. A sub-entity's funds will be held in their currency account (as per their default holding currency set up during onboarding). Your commissions will be held in your Platform currency account (set up during your own onboarding with our Platforms solution).

    All Checkout fees for processing payments will be charged to you (the platform).

      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
      {
      "id": "pay_kwrzpz644g6uxmdkpe5u6ruecm",
      "action_id": "act_ehwckitpyywunkxzou4e64iwhm",
      "amount": 1000,
      "currency": "GBP",
      "approved": true,
      "status": "Authorized",
      "auth_code": "935891",
      "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_nr35hmfxonjuvkykmuqirkgaoy",
      "type": "card",
      "expiry_month": 10,
      "expiry_year": 2030,
      "scheme": "Visa",
      "last4": "6584",
      "fingerprint": "50022A4E8D781BE774F239942C3BE78BA4E27DAF723AF559995749BE910A6E5D",
      "bin": "448504",
      "cvv_check": "Y",
      "payment_account_reference": "V001959323431657433"
      },
      "processed_on": "2021-03-26T14:16:31.4428222Z",
      "scheme_id": "314395993984285",
      "processing": {
      "acquirer_transaction_id": "925794281492281823871",
      "retrieval_reference_number": "645049548991"
      },
      "expires_on": "2021-04-25T14:16:31.4428222Z",
      "_links": {
      "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm"
      },
      "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm/actions"
      },
      "capture": {
      "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm/captures"
      },
      "void": {
      "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm/voids"
      }
      }
      }

      When you make a payment, we will let you know what stage the payment is at through webhook notifications.

      Refund a split payment

      When you refund a payment that has been split, the refund amount will come from your currency account, not the sub-entity's.

      Partial capture and incremental authorization

      You can submit a split payment during a full or partial capture request. The split amounts will be associated with their respective sub-entities.

      However, incremental authorization is not supported with split payments. While it's possible to extend a split payment's authorization validity period, any increase to the amount will be ignored when the payment is captured.

      The split information included in an authorization request will be overwritten if split information is also supplied in any subsequent requests.

      For example, if split information is submitted in both the authorization request and a partial capture request, the information in the partial capture request determines how the funds are split.

      Next steps


      About making payouts

      Full sub-entities have payout capability. Use this page to find out what you can do.

      Find out more


      Accounts API

      To get a detailed view of all required and optional fields, see our API reference.