Process payments on a lite account

Last updated: July 18, 2024

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.

Once you've enabled your sub-entity's payment capabilities, you can process payments on their behalf through our API.

Checkout.com's Integrated Platforms solution supports the following payment methods in the United Kingdom (UK) and European Economic Area (EEA):

Note

Your sub-entity will not be able to process payments until it has passed CSS onboarding checks. 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
Request a payment for multiple sub-entities (a split payment)

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 can apply commission, for reporting purposes only, by including the amount within the amount_allocations object. It will appear in the financial actions report as an additional row, defining it as commission your platform has charged from the payment.

This will not affect how funds are settled between your platform and the sub-entity. This is because all funds are settled to your platform only, and Checkout.com does not settle commission between you and your sub-entities.

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

Information

If you reconcile your platform’s commission outside of Checkout.com’s reporting, then leave the commission out of your amount_allocations array.

Use our

post

/payments endpoint to provide the payment details when requesting a payment.

When requesting a payment for a single sub-entity, you can still use the amount_allocations object to apply a commission in a minor currency unit.

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  "amount": 1000,
3  "currency": "USD",
4  "reference": "ORD-5023",
5  "description": "Three chocolate donuts",
6  "capture": true,
7  "source": {
8    "type": "card",
9    "number": "4242424242424242",
10    "expiry_month": 11,
11    "expiry_year": 2024,
12    "cvv": "100"
13  },
14  "processing_channel_id": "pc_yghfzjebuiwelerjsk3atodrey",
15  "amount_allocations": [
16    {
17      "id": "ent_125673kjsdhfksjdhf",
18      "amount": 1000
19    }
20  ]
21}

Information

You can apply commission, for reporting purposes only, by including the amount within the amount_allocations object

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}

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

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 only

To request a payment for multiple sub-entities, you must use the Full solution for Checkout.com's Integrated Platforms.

This kind of request will resemble the Request a payment examples, but with additional elements in the array.

If you receive a successful response, the payment will be automatically associated with the correct sub-entity.

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}

When you receive a 422, check the API request to make sure you've included all of the required values. For more information, see our API reference.


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["sub_entity_id_invalid"]
5}

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

Name	Description
`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.
`sub_entities_count_invalid`	Only one sub-entity ID can be requested in a Payment Facilitator business model.
`sub_entity_not_found`	No sub-entity with the given ID was found in the sub-entities list.
`sub_entity_id_invalid`	Format of the sub-entity ID in the sub-entity or sub-entities list is invalid.
`sub_entities_max_count_exceeded`	Count exceeds maximum of 10 sub-entities in a list.
`sub_entity_id_required`	The `id` is missing from one or more items in the `amount_allocations` array.
`sub_entity_amount_required`	Empty amount in sub-entity.
`sub_entity_amount_invalid`	Field out of range, input is a decimal value, or amount is less than commission.
`sub_entity_reference_length_invalid`	Reference exceeds maximum length of 50 characters.
`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.
`amount_allocations_id_duplicated`	Multiple sub-entities with the same ID.
`sub_entity_id_duplicated` (deprecated)	Multiple sub-entities with the same ID.
`refund_amount_mismatch`	Not within allowed range of the payment action.
`refund_amount_exceeds_captured_amount`	Not within allowed range of the capture amount.

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.

You can link full and partial captures and refunds to the correct sub-entity by always including the amount_allocations object. However, if you don't include it, Checkout.com will apply some default logic, as described in the following sections.

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

Funds will be credited to or debited from your platform’s currency account balance.

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 capture 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 refund 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 is 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.

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.

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 lite account

Note

Note

Link a payment with a sub-entity

Apply a sub-entity commission

Information

Request a payment

Request a payment without commission

Request a payment with commission

Information

Payment facilitators vs marketplaces

Information

Request a payment for multiple sub-entities

Response examples

Note

Captures and refunds

Full captures and refunds

Partial captures and refunds

Partial capture and refund scenarios

Incremental authorization