Skip to content

Process payments on a lite 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.

Once you've enabled your sub-entity's payment capabilities, you can process payments on their behalf through our Unified Payments 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 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.

Apply a sub-entity commission

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.

Request a payment

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.

Request a payment without commission

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
}

Request a payment with commission

Tip

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": 100
17
      }
18
    }
19
  ]
20
}

Payment facilitators vs marketplaces

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.

Request a payment for multiple sub-entities

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.

Response examples

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
}

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

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.

Full captures and refunds

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.

Partial captures and refunds

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.

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

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.

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.

Visit our API reference

On this page

Link a payment with a sub-entity
Apply a sub-entity commission
Request a payment
Request a payment for multiple sub-entities
Captures and refunds
Incremental authorization
Next steps
Find out more