Skip to content

Process payments on a full account

Last updated: March 16, 2023

Note

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, you therefore need to update your integration.

Checkout.com's Integrated Platforms solution supports the following payment methods in the UK and EEA:

Note

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

If your sub-entity is flagged for a VMSS or MATCH check, the status will be rejected. For more information on how to challenge an outcome, contact support@checkout.com.

On this page, we explain how to:

Link a payment with a sub-entity

When processing a payment on behalf of a sub-entity, you use our Unified Payments API to request a payment. 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 in the amount_allocations.id field. The sub-entity ID is returned during the onboarding process.

You may also want to take a commission, depending on your revenue model.

Apply a commission on a sub-entity payment

There are three ways to apply commission on your sub-entities' payments:

  • Fixed commission amount in minor currency units
  • Variable commission, as a percentage of the payment
  • Compound commission — a fixed commission, with an additional variable commission as a percentage of the payment amount

You can charge commission by including the amount within the amount_allocations object.

Information

If your revenue model means you do not need to use Checkout.com to charge a commission, then leave the commission out of your amount_allocations object. You can transfer funds from your sub-entities at a later stage.

Request a split payment for a single sub-entity

Your revenue model might mean that your customers use your platform to buy items from only one sub-entity at a time. You may also want to take a commission from the sub-entity for facilitating the transaction on your platform.

When requesting a split payment, use our

POST

/payments endpoint to provide the payment details.

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
  • The Platform commission
  • An optional reference

In the following example, we are charging a fixed commission of $2:

1
{
2
  "source": {
3
    "type": "token",
4
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5
  },
6
  "amount": 1000,
7
  "currency": "USD",
8
  "reference": "ORD-5023-4E89",
9
  "description": "Purchase basket",
10
  "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y",
11
  "amount_allocations": [
12
    {
13
      "id": "ent_125673kjsdhfksjdhf",
14
      "amount": 1000,
15
      "commission": {
16
        "amount": 200
17
      }
18
    }
19
  ]
20
}

Information

processing_channel_id corresponds to a specific Merchant Category Code (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.

Payment facilitators vs marketplaces

Marketplaces can specify multiple elements in the amount_allocations object, one for each sub-entity. Payment facilitators can only provide a single element in the object.

Captures and refunds for a single sub-entity payment

If you want to control how the funds flow between you and your sub-entity, always include the amount_allocations object in the capture and refund requests. However, if you don't include it, Checkout.com will apply some default logic, as described in the following sections.

For captures, the capture amount will be credited to the sub-entity's currency account balance and the commission credited to your platform.

For refunds, the refund amount will be debited from the sub-entity’s currency account balance and the commission debited from your platform

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 and a capture request, the information in the capture request determines how the funds are split.

Information

When you include the amount_allocations object in the refund request, it debits funds from the sub-entity specified. If you include a commission in the object, it debits this amount from your platform’s balance.

Full capture and refund with a single sub-entity

For full captures and refunds without the amount_allocations object, Checkout.com will always apply the amount_allocations object provided in the original authorization request, including the commission.

Partial capture and refund with a single sub-entity

For partial captures without the amount_allocations object, Checkout.com will apply the new amount specified in the partial capture to the sub-entity ID specified in the original request. We will always ignore the amount and commission of the original request.

For partial refunds without the amount_allocations object, Checkout.com will apply the new amount specified in the partial refund to the sub-entity ID specified in the original capture request. We will always ignore the amount and commission of the original request.

Partial capture and refund scenarios

If you don't include the amount_allocations object, the following happens:

Partial capture scenario

  1. You request an authorization for 100 USD on behalf of your sub-entity, and provide their id in the amount_allocations object.
  2. You submit a partial capture for 50 USD, and omit the amount_allocations object from your request.
  3. 50 USD is captured to your platform's account. The id and amount fields in the amount_allocations object are automatically set to the sub-entity ID and capture amount, respectively.

Partial refund scenario

  1. You request an authorization for 100 USD on behalf of your sub-entity, and provide their id in the amount_allocations object.
  2. You request a capture for 100 USD with the same amount_allocations object as in the authorization.
  3. You submit a partial refund for 50 USD, and omit the amount_allocations object from your request.
  4. 50 USD isa debited from your platform's account. The id and amount fields in the amount_allocations object are automatically set to the sub-entity ID and refund amount, respectively.

Request a split payment for multiple sub-entities

When a customer uses your platform to buy items from multiple sub-entities, you need to request a single 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.

How to split a payment

Send a request to our

POST

/payments endpoint that includes all required fields, along with the following.

In the amount_allocations object, 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:

  • Sub-entity A: $30 for a shirt
  • Sub-entity B: $50 for trainers
  • Sub-entity C: $20 for socks

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

Tip

Remember our APIs work in the minor currency unit.

Request example

In the following example request, we show three ways you can split the payment and specify commission for your platform:

  • Fixed commission amount: Charge the sub-entity 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 a fee of 1.5%. This sub-entity would have 1.5% of $50 deducted, so would receive $49.25. You would receive 75¢ in your currency account.
  • Compound commission: Charge the sub-entity 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
  "source": {
3
    "type": "token",
4
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5
  },
6
  "amount": 10000,
7
  "currency": "USD",
8
  "reference": "ORD-5023-4E89",
9
  "description": "Multi-seller basket",
10
  "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y",
11
  "amount_allocations": [
12
    {
13
      "id": "ent_pj6fv2w2wchfedchjjyobb4bni",
14
      "amount": 3000,
15
      "reference": "SALE-7627-8389",
16
      "commission": {
17
        "amount": 200
18
      }
19
    },
20
    {
21
      "id": "ent_kjx3tob2sxtl44wb7q7alwdu2m",
22
      "amount": 5000,
23
      "reference": "SALE-1729-3782",
24
      "commission": {
25
        "percentage": 1.5
26
      }
27
    },
28
    {
29
      "id": "ent_kklowryxmczwyoqe4z7yvcbwvy",
30
      "amount": 2000,
31
      "reference": "SALE-2127-9735",
32
      "commission": {
33
        "amount": 200,
34
        "percentage": 1.5
35
      }
36
    }
37
  ]
38
}

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, in the default holding currency selected during their onboarding. Your commissions will be held in your Platform currency account.

Note

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

1
{
2
    "id": "pay_kwrzpz644g6uxmdkpe5u6ruecm",
3
    "action_id": "act_ehwckitpyywunkxzou4e64iwhm",
4
    "amount": 10000,
5
    "currency": "USD",
6
    "approved": true,
7
    "status": "Authorized",
8
    "auth_code": "935891",
9
    "response_code": "10000",
10
    "response_summary": "Approved",
11
    "balances": {
12
        "total_authorized": 10000,
13
        "total_voided": 0,
14
        "available_to_void": 10000,
15
        "total_captured": 0,
16
        "available_to_capture": 10000,
17
        "total_refunded": 0,
18
        "available_to_refund": 0
19
    },
20
    "risk": {
21
        "flagged": false
22
    },
23
    "source": {
24
        "id": "src_nr35hmfxonjuvkykmuqirkgaoy",
25
        "type": "card",
26
        "expiry_month": 10,
27
        "expiry_year": 2030,
28
        "scheme": "Visa",
29
        "last4": "6584",
30
        "fingerprint": "50022A4E8D781BE774F239942C3BE78BA4E27DAF723AF559995749BE910A6E5D",
31
        "bin": "448504",
32
        "cvv_check": "Y",
33
        "payment_account_reference": "V001959323431657433"
34
    },
35
    "processed_on": "2021-03-26T14:16:31.4428222Z",
36
    "scheme_id": "314395993984285",
37
    "processing": {
38
        "acquirer_transaction_id": "925794281492281823871",
39
        "retrieval_reference_number": "645049548991"
40
    },
41
    "expires_on": "2021-04-25T14:16:31.4428222Z",
42
    "_links": {
43
        "self": {
44
            "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm"
45
        },
46
        "actions": {
47
            "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm/actions"
48
        },
49
        "capture": {
50
            "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm/captures"
51
        },
52
        "void": {
53
            "href": "https://api.sandbox.checkout.com/payments/pay_kwrzpz644g6uxmdkpe5u6ruecm/voids"
54
        }
55
    }
56
}

Make sure you have set up webhook notifications. This means that when you make a payment, we will tell you what stage the payment is at.

Captures and refunds for a multiple sub-entity payment

To capture or refund a payment that has been split between multiple sub-entities, provide the split information in the refund request. You can also request refunds for multiple sub-entities within a single capture or refund request.

Information

When you include the amount_allocations object in the refund request, funds are debited from the sub-entity specified. If you include a commission in the object, funds are debited from your platform’s balance.

Full refund or capture without split

The customer requests a full refund of all the items purchased in the $100 transaction.

If you do not include a split instruction, the refund request will:

  • apply the original split
  • debit the amount specified in the commission from your balance

This will look like:

  • Sub-entity A: $28, Platform: $2
  • Sub-entity B: $49.25, Platform: $0.75
  • Sub-entity C: $17.70, Platform: $2.30

Request example

1
{
2
  "source": {
3
    "type": "token",
4
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5
  },
6
  "amount": 10000,
7
  "currency": "GBP",
8
  "reference": "ORD-5023-4E89",
9
  "description": "Multi-seller basket",
10
  "processing_channel_id": "pc_hpswyyx23geezflc2ocz3exn4y",
11
  "amount_allocations": [
12
    {
13
      "id": "ent_pj6fv2w2wchfedchjjyobb4bni",
14
      "amount": 3000,
15
      "reference": "SALE-7627-8389",
16
      "commission": {
17
        "amount": 200
18
      }
19
    },
20
    {
21
      "id": "ent_kjx3tob2sxtl44wb7q7alwdu2m",
22
      "amount": 5000,
23
      "reference": "SALE-1729-3782",
24
      "commission": {
25
        "percentage": 1.5
26
      }
27
    },
28
    {
29
      "id": "ent_kklowryxmczwyoqe4z7yvcbwvy",
30
      "amount": 2000,
31
      "reference": "SALE-2127-9735",
32
      "commission": {
33
        "amount": 200,
34
        "percentage": 1.5
35
      }
36
    }
37
  ]
38
}

Full refund or capture with new split

To change how the refund is funded between you and the sub-entities, include a new split instruction.

Request example

The following example shows an amount_allocations object that specifies no commission. This funds the entire refund split amounts from the sub-entities’ balances.

1
{
2
  "id": "pay_kwrzpz644g6uxmdkpe5u6ruecm",
3
  "amount_allocations": [
4
    {
5
      "id": "ent_pj6fv2w2wchfedchjjyobb4bni",
6
      "amount": 3000
7
    },
8
    {
9
      "id": "ent_kjx3tob2sxtl44wb7q7alwdu2m",
10
      "amount": 5000,
11
      "commission": {
12
        "amount": 0
13
      }
14
    },
15
    {
16
      "id": "ent_kklowryxmczwyoqe4z7yvcbwvy",
17
      "amount": 2000
18
    }
19
  ]
20
}

Partial refund or capture with split

To partially refund a split payment, you must always include the amount_allocations object. This specifies which sub-entity or sub-entities the refund is related to.

The refund will be applied in the same way as explained in the Full refund with new split example. The amount specified in the commission will be debited from your account balance, and the remaining amount from the sub-entity balance.

Incremental authorization

Incremental authorization is not supported by the amount_allocations object. 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.

On this page

Link a payment with a sub-entity
Apply a commission on a sub-entity payment
Request a split payment for a single sub-entity
Captures and refunds for a single sub-entity payment
Request a split payment for multiple sub-entities
Captures and refunds for a multiple sub-entity payment
Incremental authorization