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 examples

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

Commissions and fees

Optional commissions and fees are deducted per lineItem.

In the above example where "itemReference"="aaa1" and the "amount": 30, a commission of £3 and a fee of £2 is taken against the £30. Leaving £25 to be paid out to "partyReference": "Sherlock Holmes".

Example extract

    "commission": {
        "narrative": {
          "line1": "Socks"
        },
        "amount": 3
      },
      "fee": {
        "narrative": {
          "line1": "Socks"
        },
        "amount": 2
      }

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

Response

Example response

Response
application/json
{
  "purchaseId": "purd1dcd2dee333cae1bfdea0",
  "purchase": {
    "items": [
      {
        "itemId": "itmd1dcd2dee333cae1bfded0",
        "itemReference": "aaa1"
      }
    ]
  }
}

Response schema

purchaseIdstring(PurchaseID)= 25 characters^pur[A-Za-z0-9_-]{21}0$required

Unique reference generated by us to identify a purchase.

purchaseobject(PurchaseResp)required
purchase.​itemsArray of objects(ItemsResp)required
purchase.​items[].​itemIdstring(ItemID)= 25 characters^itm[A-Za-z0-9_-]{21}0$required

Unique reference generated by us to identify a purchase item.

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

Unique reference generated by you to identify a purchase item.

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