APIs
/
Split Payments
/
Fully Settle/Refund a Payment

Split Payments (2025-06-25)

Divide funds from a single payment amongst yourself and your parties/sellers.

Authentication Set your headers

    Authorization: {your_credentials}
    WP-Api-Version: 2025-06-25

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to your by your Implementation Manager.

DNS Whitelisting

Whitelist the following URLs:

  • https://try.access.worldpay.com/
  • https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License

Worldpay

Languages
Servers
Try

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

Live

https://access.worldpay.com/

Create Split Payments Request.

Request

Create a split payments that you can split into two or more payments.

Security
BasicAuth
Headers
Content-Typestringrequired

The Content-Type.

Example: application/json
WP-Api-Versionstringrequired

The API version.

Example: 2025-06-25
Bodyapplication/jsonrequired
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.

fulfillmentobjectrequired
autobooleanrequired

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

paymentCommandIdstring= 25 characters^cmd[A-Za-z0-9_-]{21}0$required

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.

merchantobjectrequired
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"
valueobjectrequired
currencystring^[A-Z]{3}$required

The 3 letter ISO-4217 currency code.

Example: "GBP"
totalAmountintegerrequired

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

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

Unique reference generated by you to identify a line item.

partyReferencestring[ 1 .. 64 ] charactersrequired

Unique reference generated by you to identify a party.

amountintegerrequired

Implied decimal. For example, 250 GBP = £2.50

Example: 250
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.

deductionsArray of objects
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"
        }
      ]
    }
  ]
}

Responses

Merchant Pay-in accepted

Headers
WP-CorrelationIdstring(uuid)
Example: "c85762a8-93af-47e7-beae-345d3dddbe94"
Bodyapplication/json
splitPaymentIdstring= 25 characters^spl[A-Za-z0-9_-]{21}0$required

Unique reference generated by us to identify a split payment.

lineItemsobjectrequired
itemsArray of objects
Response
application/json
{
  "splitPaymentId": "spl9wdyDYROy6-boa2mSFfn20",
  "lineItems": [
    {
      "itemId": "itmZRsCU4vjopY6q9HH9znXQ0",
      "itemReference": "aaa1"
    },
    {
      "itemId": "itmO9IHhLjjamTh9oHcR1wH-0",
      "itemReference": "bbb1"
    }
  ]
}

Fully Settle/Refund a Payment

Request

Confirm a settlement/refund of all line items within a split payment.

Security
BasicAuth
Path
splitPaymentIdstring= 25 characters^spl[A-Za-z0-9_-]{21}0$required

ID of the split payment.

Example: spld1dcd2dee333cae1bfdea0
Headers
Content-Typestringrequired

The Content-Type.

Example: application/json
WP-Api-Versionstringrequired

The API version.

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

A reference generated by you to identify each lifecycle event of a payment.

descriptionstring<= 50 characters

Description of the fulfillment

Example: "optional description of fulfillment"
paymentCommandIdstring= 25 characters^cmd[A-Za-z0-9_-]{21}0$required

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.

transactionTypestringrequired

Defines the type of payment lifecycle action.

Enum"settle""refund"
Example: "settle"
application/json
{
  "reference": "5D262CB9-57F2-4176-AA7C-B76A79284276",
  "description": "optional description of fulfillment",
  "paymentCommandId": "cmdJxsTja3Daad6dig338w2R0",
  "transactionType": "settle"
}

Responses

Merchant Pay-in accepted

Headers
WP-CorrelationIdstring(uuid)
Example: "c85762a8-93af-47e7-beae-345d3dddbe94"
Bodyapplication/json
fulfillmentstring

Update status to fulfilled

Response
application/json
{
  "fulfillment": "accepted"
}

Partially Settle/Refund a Payment

Request

Confirm a settlement/refund of individual line items within a payment.

Security
BasicAuth
Path
splitPaymentIdstring= 25 characters^spl[A-Za-z0-9_-]{21}0$required

ID of the split payment.

Example: spld1dcd2dee333cae1bfdea0
itemIdstring= 25 characters^itm[A-Za-z0-9_-]{21}0$required

ID of the line item listed in a split payment request.

Headers
Content-Typestringrequired

The Content-Type.

Example: application/json
WP-Api-Versionstringrequired

The API version.

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

Command reference generated by you.

descriptionstring<= 50 characters

Description of the fulfillment

Example: "optional description of fulfillment"
paymentCommandIdstring= 25 characters^cmd[A-Za-z0-9_-]{21}0$required

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.

transactionTypestringrequired

Defines the type of payment lifecycle action.

Enum"settle""refund"
Example: "settle"
application/json
{
  "reference": "5D262CB9-57F2-4176-AA7C-B76A79284276",
  "description": "optional description of fulfillment",
  "paymentCommandId": "cmdJxsTja3Daad6dig338w2R0",
  "transactionType": "settle"
}

Responses

Merchant Pay-in accepted

Headers
WP-CorrelationIdstring(uuid)
Example: "c85762a8-93af-47e7-beae-345d3dddbe94"
Bodyapplication/json
fulfillmentstring

Update status to fulfilled

Response
application/json
{
  "fulfillment": "accepted"
}