New service | Last updated: 14 May 2025
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
Only split a purchase once you have submitted the final amount to be authorized.
POST
https://try.access.worldpay.com/splitPayments/purchases
Request examples
{ "purchaseId": "purd1dcd2dee333cae1bfdea0", "purchase": { "items": [ { "itemId": "itmd1dcd2dee333cae1bfded0", "itemReference": "aaa1" } ] } }
Request schema
Reference for the purchase generated by you.
Set to 'true' for auto fulfillment, otherwise to 'false'
A unique ID generated by us for each lifecycle event on a payment. You have received this in the response of your payment authorization request in our Card Payments API.
Command reference generated by you.
Used to route the request in Access Worldpay, created as part of on-boarding.
The text that appears on your customer's statement.
Implied decimal. For example, 250 USD = $2.50.
Unique reference generated by you to identify a purchase item.
Unique reference generated by you to identify a party.
Implied decimal. For example, 250 USD = $2.50
The text that appears on your customer's statement.
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
{ "purchaseId": "purd1dcd2dee333cae1bfdea0", "purchase": { "items": [ { "itemId": "itmd1dcd2dee333cae1bfded0", "itemReference": "aaa1" } ] } }
Response schema
Unique reference generated by us to identify a purchase.
Unique reference generated by us to identify a purchase item.
Unique reference generated by you to identify a purchase item.
Errors
Check out our API reference for the full error code schema.
If you have set fulfillment.auto
to false
you must now settle your payment.
Next Steps