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

application/json

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

referencestringrequired

Reference for the split payments generated by you.

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

Text to appear on the customer's billing statement. Sometimes referred to as a billing descriptor. If this isn't set, the value from the merchant profile is used.

fulfillmentobject(AutoFulfillment)required
fulfillment.​autobooleanrequired

Set to 'true' for auto fulfillment, otherwise to 'false'

fulfillment.​paymentCommandIdstring(PaymentCommandID)= 25 characters^cmd[A-Za-z0-9_-]{21}0$required
merchantobject(Merchant)required
merchant.​entitystring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"
valueobject(Value)required
value.​currencystring(Currency)^[A-Z]{3}$required
Example: "GBP"
value.​totalAmountinteger(TotalAmount)required

Implied decimal. For example, 250 GBP = £2.50.

Example: 250
lineItemsArray of objects(LineItems)required
lineItems[].​itemReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

Unique reference generated by you to identify a line item.

lineItems[].​partyReferencestring[ 1 .. 64 ] charactersrequired

Unique reference generated by you to identify a party.

lineItems[].​amountinteger(Amount)required

Implied decimal. For example, 250 GBP = £2.50

Example: 250
lineItems[].​descriptionstring<= 50 characters^[a-zA-Z0-9 ,./-]*$

Text to appear on the customer's billing statement. Sometimes referred to as a billing descriptor. If this isn't set, the value from the merchant profile is used.

lineItems[].​deductionsArray of objects(Deductions)

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

application/json
No response example

Response schema

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

Unique reference generated by us to identify a split payment.

lineItemsobject(SplitResp)required
lineItems.​itemsArray of objects(LineItemsResp)

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