Skip to content

New service | Last updated: 01 July 2025

Split a payment

Example use case

This example outlines a split payment journey within a food delivery marketplace platform. Ensuring a seamless experience for customer, restaurant and driver.

Scenario: A customer orders a food delivery from a local restaurant, the Baker Street Café, to their home.

  1. Order placement: Customer makes food order for £100.
  2. Order acceptance and delivery: Restaurant accepts order and sends food via delivery driver.
  3. Payment distribution: The food delivery marketplace splits the "totalAmount": 10000 as follows:
    • restaurant: "amount": 9000, with a commission of 1% being taken by the food delivery marketplace. The marketplace therefore receives £0.10 in their virtual Worldpay bank account, leaving £89.10 to be paid out to partyReference: "The Baker Street Café"
    • delivery driver: "amount": 1000, with a fee of £2 being taken by the food delivery marketplace, which they will receive in their virtual Worldpay bank account. Leaving £8 to be paid out to "partyReference": John Watson"

Request

Best Practice

Only split a payment once you have submitted the final amount to be authorized.

POST https://try.access.worldpay.com/splitPayments

Request examples

Example request for creating a split payment

{
  "reference": "5D262CB9-57F2-4176-AA7C-B76A79284277",
  "description": "optional split payment description",
  "fulfillment": {
    "auto": false,
    "paymentCommandId": "cmdJxsTja3Daad6dig338w2R0"
  },
  "merchant": {
    "entity": "default"
  },
  "value": {
    "currency": "GBP",
    "totalAmount": 10000
  },
  "lineItems": [
    {
      "itemReference": "aaa1",
      "partyReference": "The Baker Street Café",
      "amount": 9000,
      "description": "Item description",
      "deductions": [
        {
          "type": "commission",
          "value": {
            "type": "percentage",
            "amount": 1
          },
          "description": "Deduction description"
        }
      ]
    },
    {
      "itemReference": "bbb1",
      "partyReference": "John Watson",
      "amount": 1000,
      "description": "Item description",
      "deductions": [
        {
          "type": "fee",
          "value": {
            "type": "flat",
            "amount": 200
          },
          "description": "Deduction description"
        }
      ]
    }
  ]
}

Request schema

referencestring, [ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]+$required

A reference generated by you to identify the split payments.

descriptionstring, <= 50 characters^[a-zA-Z0-9 ,./-]*$

Used to identify a split payment of an order to help with reconciliation purposes. When used, the values appear in the Payouts Portal.

fulfillmentobject(AutoFulfillment)required
merchantobject(Merchant)required
valueobject(Value)required
lineItemsArray of objects(LineItems)required

Deductions

Optional commissions and fees are deducted per lineItem.

In the above example where "itemReference"="aaa1" and the "amount": 90, a commission of 1% is taken against the £90. Leaving £89.10 to be paid out to "partyReference": "The Baker Street Café".

There is also a second deduction taken against "itemReference"="bbb2" with "amount": 10. In the request a flat fee of £2 is taken. The remainder of £8 will be paid out to "partyReference": "John Watson"

Example extract

"deductions": [
        {
          "type": "commission",
          "value": {
            "type": "percentage",
            "amount": 1
          },
          "description": "Deduction description"
        }

View our full request and response schema in our API reference.

Response

Example response

Example request for creating a split payment

{
  "reference": "5D262CB9-57F2-4176-AA7C-B76A79284277",
  "description": "optional split payment description",
  "fulfillment": {
    "auto": false,
    "paymentCommandId": "cmdJxsTja3Daad6dig338w2R0"
  },
  "merchant": {
    "entity": "default"
  },
  "value": {
    "currency": "GBP",
    "totalAmount": 10000
  },
  "lineItems": [
    {
      "itemReference": "aaa1",
      "partyReference": "The Baker Street Café",
      "amount": 9000,
      "description": "Item description",
      "deductions": [
        {
          "type": "commission",
          "value": {
            "type": "percentage",
            "amount": 1
          },
          "description": "Deduction description"
        }
      ]
    },
    {
      "itemReference": "bbb1",
      "partyReference": "John Watson",
      "amount": 1000,
      "description": "Item description",
      "deductions": [
        {
          "type": "fee",
          "value": {
            "type": "flat",
            "amount": 200
          },
          "description": "Deduction description"
        }
      ]
    }
  ]
}

Response schema

splitPaymentIdstring, = 25 characters(SplitPaymentID)^spl[A-Za-z0-9_-]{21}0$required

Unique reference generated by us to identify a split payment.

lineItemsobject(SplitResp)required

Errors

Check out our API reference for the full error code schema.

Note

If you have set fulfillment.auto to false you must now settle your payment.

Next steps

Settle your purchase
Refund your purchase