Skip to content
Platforms / Payments

Sub-entity payments

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

      Our Unified Payments API allows you to adapt the standard payments flow. However, two features will not produce the desired effects on payments that have been split.

      • Incremental authorization will have no effect. It's possible to extend a split payment's authorization validity period, but any extension to the amount will be ignored when the payment is captured.
      • Partial capture will treat the payment as if there has been no split and will not be associated to any sub-entity.

      Next steps

      About making payouts

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

      Read our payouts documentation

      Find out more

      Accounts API

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

      Visit our API reference

      On this page

      Link a payment with a sub-entity
      Charge a sub-entity commission
      Request a payment for a single sub-entity
      Request a payment for multiple sub-entities
      Next steps
      Find out more