New service | Last updated: 14 May 2025

Important

This documentation is for preview purposes only.

Split a purchase

What is a purchase?

A purchase is made up of one or more orders. We refer to these as lineItems in the API. You can use these lineItems to disburse funds of a payment to multiple beneficiaries, including yourself.

Request

Best Practice

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

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

Request/response examples

application/json

For every purchase you can define how you want to split the funds between the number of entities that belong to yourself and the beneficiaries on your platform

{
  "purchaseReference": "5D262CB9-57F2-4176-AA7C-B76A79284277",
  "fulfillment": {
    "auto": false,
    "commandId": "cmdJxsTja3Daad6dig338w2R0",
    "commandReference": "5D262CB9-57F2-4176-AA7C-B76A79284276"
  },
  "merchant": {
    "entity": "default"
  },
  "narrative": {
    "line1": "Socks",
    "line2": "Sandals"
  },
  "value": {
    "currency": "GBP",
    "totalAmount": 50
  },
  "items": [
    {
      "itemReference": "aaa1",
      "partyReference": "Sherlock Holmes",
      "amount": 30,
      "narrative": {
        "line1": "Socks"
      },
      "commission": {
        "narrative": {
          "line1": "Socks"
        },
        "amount": 3
      },
      "fee": {
        "narrative": {
          "line1": "Socks"
        },
        "amount": 2
      }
    },
    {
      "itemReference": "bbb1",
      "partyReference": "John Watson",
      "amount": 20,
      "narrative": {
        "line1": "Sandals"
      },
      "commission": {
        "narrative": {
          "line1": "Sandals"
        },
        "amount": 3
      },
      "fee": {
        "narrative": {
          "line1": "Sandals"
        },
        "amount": 2
      }
    }
  ]
}
Response
application/json
{
  "purchaseId": "purd1dcd2dee333cae1bfdea0",
  "purchase": {
    "items": [
      {
        "itemId": "itmd1dcd2dee333cae1bfded0",
        "itemReference": "aaa1"
      }
    ]
  }
}

Request schema

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

Reference for the purchase generated by you.

fulfillmentobject(AutoFulfillment)required
fulfillment.​autobooleanrequired

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

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

Command reference generated by you.

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"
narrativeobject(Narrative)

The text that appears on your customer's statement.

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

Implied decimal. For example, 250 USD = $2.50.

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

Unique reference generated by you to identify a purchase item.

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

Unique reference generated by you to identify a party.

items[].​amountinteger(Amount)required

Implied decimal. For example, 250 USD = $2.50

Example: 250
items[].​narrativeobject(Narrative)

The text that appears on your customer's statement.

items[].​commissionobject
items[].​feeobject

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

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