Skip to content

Sub-entity payments

Last updated: September 07, 2022

A previous version of this page included the marketplace object in code examples. This has since been deprecated and replaced by the amount_allocations object.

If you're using the marketplace object, please update your integration.

Once your sub-entity's payment capabilities have been enabled, you can process payments on their behalf 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.

Your sub-entity will not be able to process payments until it has passed onboarding checks (CSS, PEP, KYC and KYB).


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.

So we know the payment is on behalf of your sub-entity, you also need to provide the sub-entity's ID using the id field in an element of the amount_allocations 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 charge commission by including the amount within the amount_allocations object.


Request a payment for a single sub-entity

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

When requesting a payment for a single sub-entity, you can still use the amount_allocations object to charge a commission.

    PayFacs only

    To associate this payment with the correct sub-entity, use the amount_allocations object, providing a single object with the appropriate sub-entity id and the total amount.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    {
    "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",
    "amount_allocations": [
    {
    "id": "ent_125673kjsdhfksjdhf",
    "amount": 1000
    }
    ]
    }

    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 amount_allocations array, include an object for each sub-entity that 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
    {
    "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
    },
    "amount": 10000,
    "currency": "GBP",
    "reference": "ORD-5023-4E89",
    "description": "Multi-seller basket",
    "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y",
    "amount_allocations": [
    {
    "id": "ent_pj6fv2w2wchfedchjjyobb4bni",
    "amount": 3000,
    "reference": "SALE-7627-8389",
    "commission": {
    "amount": 200
    }
    },
    {
    "id": "ent_kjx3tob2sxtl44wb7q7alwdu2m",
    "amount": 3000,
    "reference": "SALE-1729-3782",
    "commission": {
    "percentage": 1.5
    }
    },
    {
    "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

      You can refund a payment that has been split, but you cannot provide split information in the refund request. Refunds must be sent separately for each sub-entity.

      The refund amount will come from your currency account, not the sub-entity's account.

      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.