Process payments on a full account

Last updated: July 26, 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 [email protected].

On this page, we explain how to:

Link a payment with a sub-entity
Apply a commission on each payment
Request a payment for a single sub-entity or multiple sub-entities (a split payment)
Capture or refund a split payment, either fully or partially

When processing a payment on behalf of a sub-entity, you use our 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.

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.

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.

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.

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.

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.

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.

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

Partial capture scenario

You request an authorization for 100 USD on behalf of your sub-entity, and provide their id in the amount_allocations object.
You submit a partial capture for 50 USD, and omit the amount_allocations object from your request.
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

You request an authorization for 100 USD on behalf of your sub-entity, and provide their id in the amount_allocations object.
You request a capture for 100 USD with the same amount_allocations object as in the authorization.
You submit a partial refund for 50 USD, and omit the amount_allocations object from your request.
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.

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.

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.

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.

Information

Remember our APIs work in the minor currency unit.

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}

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}

This is a list of error codes specifically related to split payments.

Name	Description
`amount_allocations_id_duplicated`	Multiple sub-entities with the same ID.
`amount_allocations_required`	The processing channel used in this payment request has the business model of payment facilitator or marketplace, but the `amount_allocations` object has not been provided.
`marketplace_required`	Deprecated. The processing channel used in this payment request has the business model of payment facilitator or marketplace, but the `marketplace` object has not been provided.
`refund_amount_exceeds_captured_amount`	Not within allowed range of the capture amount.
`refund_amount_mismatch`	Not within allowed range of the payment action.
`sub_entities_count_invalid`	Only one sub-entity ID can be requested in a Payment Facilitator business model.
`sub_entities_max_count_exceeded`	Count exceeds maximum of 10 sub-entities in a list.
`sub_entity_amount_invalid`	Field out of range, input is a decimal value, or amount is less than commission.
`sub_entity_amount_required`	Empty amount in sub-entity.
`sub_entities_capture_balances_not_found`	The payment in this refund request does not support refund splits. Try again without the `amount_allocations` object.
`sub_entity_commission_amount_invalid`	Not within allowed range of the payment action, or input is a decimal value.
`sub_entity_commission_percentage_invalid`	Not within allowed range (0%-100%), or value is too long.
`sub_entity_id_cannot_be_entity_id`	The `amount_allocations` object only accepts sub-entity IDs, not client entity IDs.
`sub_entity_id_duplicated`	Deprecated. Multiple sub-entities with the same ID.
`sub_entity_id_invalid`	Format of the sub-entity ID in the sub-entity or sub-entities list is invalid.
`sub_entity_id_required`	The `id` is missing from one or more items in the `amount_allocations` array.
`sub_entity_not_found`	No sub-entity with the given ID was found in the sub-entities list.
`sub_entity_reference_length_invalid`	Reference exceeds maximum length of 50 characters.

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.

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.

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


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}

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

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}

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

Process payments on a full account

Note

Note

Link a payment with a sub-entity

Apply a commission on a sub-entity payment

Information

Request a split payment for a single sub-entity

Information

Payment facilitators vs marketplaces

Captures and refunds for a single sub-entity payment

Information

Full capture and refund with a single sub-entity

Partial capture and refund with a single sub-entity

Partial capture and refund scenarios

Request a split payment for multiple sub-entities

How to split a payment

Split payments example scenario

Information

Request example

Response examples

Note

Captures and refunds for a multiple sub-entity payment

Information

Full refund or capture without split

Request example

Full refund or capture with new split

Request example

Partial refund or capture with split

Incremental authorization