The SplitPayments API from Worldpay — 3 operation(s) for splitpayments.
openapi: 3.0.1
info:
title: 3DS 3DS actions SplitPayments API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: SplitPayments
paths:
/splitPayments:
post:
summary: Create split payments request
description: Create a request allowing you to split your payment.
operationId: splitPayments
parameters:
- name: Content-Type
in: header
description: The Content-Type.
required: true
schema:
type: string
description: The Content-Type.
example: application/json
example: application/json
- name: WP-Api-Version
in: header
description: The API version.
required: true
schema:
type: string
description: The API version.
example: '2025-06-25'
example: '2025-06-25'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SplitRequest'
examples:
SplitPayment:
$ref: '#/components/examples/split'
required: true
responses:
'201':
description: Merchant Pay-in accepted
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/SplitResponse'
examples:
Purchase:
$ref: '#/components/examples/split-201'
'400':
description: Bad request format or data
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithValidationErrors'
examples:
headerIsMissing:
$ref: '#/components/examples/400-headerIsMissing'
bodyIsEmpty:
$ref: '#/components/examples/400-bodyIsEmpty'
bodyIsNotJson:
$ref: '#/components/examples/400-bodyIsNotJson'
bodyDoesNotMatchSchema:
$ref: '#/components/examples/400-bodyDoesNotMatchSchema'
'401':
description: Un-authorized access, Insufficient permissions to fulfil request.
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse401'
examples:
unauthorizedAccess:
$ref: '#/components/examples/401-unauthorizedAccess'
headerHasInvalidValue:
$ref: '#/components/examples/401-headerHasInvalidValue'
headerIsMissing:
$ref: '#/components/examples/401-headerIsMissing'
'406':
description: The API version is not supported
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse406'
examples:
headerHasInvalidValue:
$ref: '#/components/examples/406'
'415':
description: Media type not supported
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse415'
examples:
headerHasInvalidValue:
$ref: '#/components/examples/415'
'422':
description: Wrong party info, or no balanceAccount
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse422'
examples:
fieldHasInvalidValue:
$ref: '#/components/examples/422-FieldHasInvalidValue'
fieldIsMissing:
$ref: '#/components/examples/422-FieldIsMissing'
'500':
description: internalErrorOccurred
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse500'
examples:
Internal server error:
$ref: '#/components/examples/500'
x-noTag: noTag
x-orderingPosition: '1'
tags:
- SplitPayments
/splitPayments/{splitPaymentId}/fulfillments:
post:
summary: Fully settle/refund a payment
description: Confirm a settlement/refund of all line items within a split payment.
operationId: fullCaptureFulfillments
parameters:
- name: splitPaymentId
in: path
required: true
schema:
type: string
minLength: 25
maxLength: 25
pattern: ^spl[A-Za-z0-9_-]{21}0$
example: spld1dcd2dee333cae1bfdea0
description: ID of the split payment.
- name: Content-Type
in: header
description: The Content-Type.
required: true
schema:
type: string
description: The Content-Type
example: application/json
example: application/json
- name: WP-Api-Version
in: header
description: The API version.
required: true
schema:
type: string
description: The API version.
example: '2025-06-25'
example: '2025-06-25'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FulfillmentsRequest'
examples:
Full Settlement:
$ref: '#/components/examples/FulfillmentsRequest'
Full Refund:
$ref: '#/components/examples/RefundRequest'
required: true
responses:
'201':
description: Merchant Pay-in accepted
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/FulfillmentsResponse'
examples:
Full Settlement:
$ref: '#/components/examples/fulfillments-201'
'400':
description: Bad request format or data
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithValidationErrors'
examples:
headerIsMissing:
$ref: '#/components/examples/400-headerIsMissing'
bodyIsEmpty:
$ref: '#/components/examples/400-bodyIsEmpty'
bodyIsNotJson:
$ref: '#/components/examples/400-bodyIsNotJson'
bodyDoesNotMatchSchema:
$ref: '#/components/examples/400-bodyDoesNotMatchSchema'
'401':
description: Un-authorized access, insufficient permissions to fulfil request
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse401'
examples:
unauthorizedAccess:
$ref: '#/components/examples/401-unauthorizedAccess'
headerHasInvalidValue:
$ref: '#/components/examples/401-headerHasInvalidValue'
headerIsMissing:
$ref: '#/components/examples/401-headerIsMissing'
'406':
description: The API version is not supported
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse406'
examples:
headerHasInvalidValue:
$ref: '#/components/examples/406'
'415':
description: Media type not supported
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse415'
examples:
headerHasInvalidValue:
$ref: '#/components/examples/415'
'500':
description: internalErrorOccurred
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse500'
examples:
Internal server error:
$ref: '#/components/examples/500'
x-orderingPosition: '2'
tags:
- SplitPayments
/splitPayments/{splitPaymentId}/items/{itemId}/fulfillments:
post:
summary: Partially settle/refund a payment
description: Confirm a settlement/refund of individual line items within a payment.
operationId: singItemCaptureFulfillments
parameters:
- name: splitPaymentId
in: path
required: true
schema:
type: string
minLength: 25
maxLength: 25
pattern: ^spl[A-Za-z0-9_-]{21}0$
example: spld1dcd2dee333cae1bfdea0
description: ID of the split payment.
- name: itemId
in: path
required: true
schema:
$ref: '#/components/schemas/ItemID'
description: ID of the line item listed in a split payment request.
- name: Content-Type
in: header
description: The Content-Type.
required: true
schema:
type: string
example: application/json
example: application/json
- name: WP-Api-Version
in: header
schema:
type: string
description: The API version.
example: '2025-06-25'
example: '2025-06-25'
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ItemFulfillmentsRequest'
examples:
Single Item Settlement:
$ref: '#/components/examples/FulfillmentRequestSingle'
Single Item Refund:
$ref: '#/components/examples/RefundRequest'
required: true
responses:
'201':
description: Merchant Pay-in accepted
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ItemFulfillmentsResponse'
examples:
Single Item Settlement:
$ref: '#/components/examples/fulfillments-201'
'400':
description: Bad request format or data
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithValidationErrors'
examples:
headerIsMissing:
$ref: '#/components/examples/400-headerIsMissing'
bodyIsEmpty:
$ref: '#/components/examples/400-bodyIsEmpty'
bodyIsNotJson:
$ref: '#/components/examples/400-bodyIsNotJson'
bodyDoesNotMatchSchema:
$ref: '#/components/examples/400-bodyDoesNotMatchSchema'
'401':
description: Un-authorized access, insufficient permissions to fulfil request
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse401'
examples:
unauthorizedAccess:
$ref: '#/components/examples/401-unauthorizedAccess'
headerHasInvalidValue:
$ref: '#/components/examples/401-headerHasInvalidValue'
headerIsMissing:
$ref: '#/components/examples/401-headerIsMissing'
'406':
description: The API version is not supported
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse406'
examples:
headerHasInvalidValue:
$ref: '#/components/examples/406'
'415':
description: Media type not supported
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse415'
examples:
headerHasInvalidValue:
$ref: '#/components/examples/415'
'500':
description: internalErrorOccurred
headers:
WP-CorrelationId:
example: c85762a8-93af-47e7-beae-345d3dddbe94
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse500'
examples:
Internal server error:
$ref: '#/components/examples/500'
x-orderingPosition: '3'
tags:
- SplitPayments
components:
examples:
401-unauthorizedAccess:
value:
errorName: unauthorizedAccess
message: The provided secret does not contain valid authentication.
401-headerHasInvalidValue:
value:
errorName: headerHasInvalidValue
message: A header 'WP-CorrelationId' in the request does not contain an expected pattern.
RefundRequest:
value:
reference: 5D262CB9-57F2-4176-AA7C-B76A79284276
description: optional description of fulfillment
paymentCommandId: cmdJxsTja3Daad6dig338w2R0
transactionType: refund
400-bodyDoesNotMatchSchema:
value:
errorName: bodyDoesNotMatchSchema
message: There were field validation errors. The errors that occurred are within the validationErrors array.
validationErrors:
- errorName: fieldIsEmpty
message: must not be blank
jsonPath: domain
- errorName: fieldIsEmpty
message: must not be blank
jsonPath: subject
400-bodyIsEmpty:
value:
errorName: bodyIsEmpty
message: The body within the request is empty. A body is required to be non-empty.
FulfillmentsRequest:
value:
reference: 5D262CB9-57F2-4176-AA7C-B76A79284276
description: optional description of fulfillment
paymentCommandId: cmdJxsTja3Daad6dig338w2R0
transactionType: settle
422-FieldHasInvalidValue:
value:
errorName: fieldHasInvalidValue
message: The party with reference '{{input reference } }' is not active, please re-activate it before using it for payIns or payOuts.
'500':
value:
errorName: internalErrorOccurred
message: An error occurred within the service.
fulfillments-201:
value:
fulfillment: accepted
'415':
value:
errorName: headerHasInvalidValue
message: A header 'Content-Type' in the request does not contain an expected value. Content-type must be - application/vnd.worldpay.split-payments-service-v1+json
'406':
value:
errorName: headerHasInvalidValue
message: A header 'Accept' in the request does not contain an expected pattern. It must be application/json, or not set.
FulfillmentRequestSingle:
value:
reference: 5D262CB9-57F2-4176-AA7C-B76A79284276
description: optional description of fulfillment
paymentCommandId: cmdJxsTja3Daad6dig338w2R0
transactionType: settle
split-201:
value:
splitPaymentId: spl9wdyDYROy6-boa2mSFfn20
lineItems:
- itemId: itmZRsCU4vjopY6q9HH9znXQ0
itemReference: aaa1
- itemId: itmO9IHhLjjamTh9oHcR1wH-0
itemReference: bbb1
400-bodyIsNotJson:
value:
errorName: bodyIsNotJson
message: The body within the request is not a valid JSON. This body is required to be a valid JSON.
401-headerIsMissing:
value:
errorName: headerIsMissing
message: A required header field is missing.
400-headerIsMissing:
value:
errorName: headerIsMissing
message: A mandatory request header field is missing. The name of the missing request header field is %s.
422-FieldIsMissing:
value:
errorName: fieldIsMissing
message: There is no payoutInstrument for the settlement currency, to resolve this please create a payoutInstrument by calling POST /parties/{{this}}/payoutInstruments for the settlement currency.
split:
description: Example request for creating a split payment
value:
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
schemas:
ValidationError:
required:
- errorName
- message
- jsonPath
type: object
properties:
errorName:
type: string
description: A machine and human readable error type for clarity and semantic understanding of the error.
enum:
- fieldIsNull
- fieldIsEmpty
- numberIsTooLarge
- numberIsTooSmall
- stringFailedRegexCheck
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*.
jsonPath:
type: string
description: The field presents the JSONPath of th element within the request body associated with the error.
SplitRequest:
required:
- reference
- fulfillment
- merchant
- value
- lineItems
properties:
reference:
type: string
description: Reference for the split payments generated by you.
description:
maxLength: 50
pattern: ^[a-zA-Z0-9 ,./-]*$
type: string
description: 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.
fulfillment:
$ref: '#/components/schemas/AutoFulfillment'
merchant:
$ref: '#/components/schemas/Merchant'
value:
$ref: '#/components/schemas/Value'
lineItems:
$ref: '#/components/schemas/LineItems'
Currency:
type: string
description: The [3 letter ISO-4217 currency code](/products/reference/supported-countries-currencies#iso-currency-codes).
example: GBP
pattern: ^[A-Z]{3}$
ErrorResponse406:
type: object
required:
- errorName
- message
properties:
errorName:
type: string
description: A header 'WP-Api-Version' or URL path in the request is misconfigured
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*.
LineItems:
type: array
items:
required:
- itemReference
- partyReference
- amount
type: object
properties:
itemReference:
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
type: string
description: Unique reference generated by you to identify a line item.
partyReference:
maxLength: 64
minLength: 1
type: string
description: Unique reference generated by you to identify a party.
amount:
$ref: '#/components/schemas/Amount'
description:
maxLength: 50
pattern: ^[a-zA-Z0-9 ,./-]*$
type: string
description: 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.
deductions:
$ref: '#/components/schemas/Deductions'
SplitResp:
type: object
properties:
items:
$ref: '#/components/schemas/LineItemsResp'
ErrorResponse500:
type: object
required:
- errorName
- message
properties:
errorName:
type: string
enum:
- internalErrorOccurred
description: An error occurred within the service.
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*.
PaymentCommandID:
type: string
description: 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](/products/card-payments/openapi/other/authorize#other/authorize/t=response&c=201&path=&d=0/commandid) in our Card Payments API.
minLength: 25
maxLength: 25
pattern: ^cmd[A-Za-z0-9_-]{21}0$
Value:
required:
- currency
- totalAmount
type: object
properties:
currency:
$ref: '#/components/schemas/Currency'
totalAmount:
$ref: '#/components/schemas/TotalAmount'
ItemFulfillmentsResponse:
type: object
properties:
fulfillment:
type: string
description: Update status to fulfilled
FulfillmentsRequest:
required:
- paymentCommandId
- transactionType
type: object
properties:
reference:
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
type: string
description: A reference generated by you to identify each lifecycle event of a payment.
description:
type: string
maxLength: 50
description: Description of the fulfillment
example: optional description of fulfillment
paymentCommandId:
$ref: '#/components/schemas/PaymentCommandID'
transactionType:
$ref: '#/components/schemas/TransactionType'
SplitResponse:
type: object
required:
- splitPaymentId
- lineItems
properties:
splitPaymentId:
$ref: '#/components/schemas/SplitPaymentID'
lineItems:
$ref: '#/components/schemas/SplitResp'
ErrorResponseWithValidationErrors:
type: object
required:
- errorName
- message
properties:
errorName:
type: string
enum:
- headerIsMissing
- headerHasInvalidValue
- bodyIsEmpty
- bodyIsNotJson
- bodyDoesNotMatchSchema
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*.
validationErrors:
type: array
description: If there were field validation errors, they will be collected in this array.
items:
$ref: '#/components/schemas/ValidationError'
Deductions:
type: array
items:
type: object
required:
- type
- value
properties:
type:
type: string
description: Type of deduction.
enum:
- commission
- fee
example: commission
value:
type: object
required:
- type
- amount
properties:
type:
type: string
description: Type of value.
enum:
- percentage
- flat
example: percentage
amount:
type: integer
example: 75
description: percentage or flat amount of the deduction. For example, 75 = 0.75% or £0.75
description:
type: string
maxLength: 50
description: Description of the deduction.
example: Deduction description
AutoFulfillment:
required:
- auto
- paymentCommandId
type: object
properties:
auto:
type: boolean
description: Set to 'true' for auto fulfillment, otherwise to 'false'
paymentCommandId:
$ref: '#/components/schemas/PaymentCommandID'
ItemFulfillmentsRequest:
required:
- paymentCommandId
- transactionType
type: object
properties:
reference:
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
type: string
description: Command reference generated by you.
description:
type: string
maxLength: 50
description: Description of the fulfillment
example: optional description of fulfillment
paymentCommandId:
$ref: '#/components/schemas/PaymentCommandID'
transactionType:
$ref: '#/components/schemas/TransactionType'
Amount:
type: integer
example: 250
description: Implied decimal. For example, 250 GBP = £2.50
ErrorResponse401:
required:
- errorName
- message
type: object
properties:
errorName:
type: string
enum:
- unauthorizedAccess
- headerHasInvalidValue
- headerIsMissing
description: Un-authorized access, Insufficient permissions to fulfil request.
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*.
SplitPaymentID:
type: string
description: Unique reference generated by us to identify a split payment.
minLength: 25
maxLength: 25
pattern: ^spl[A-Za-z0-9_-]{21}0$
Merchant:
required:
- entity
type: object
properties:
entity:
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
type: string
description: Used to route the request in Access Worldpay, created as part of on-boarding.
example: default
LineItemsResp:
type: array
items:
required:
- itemId
- itemReference
type: object
properties:
itemId:
$ref: '#/components/schemas/ItemID'
itemReference:
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
type: string
description: Unique reference generated by you to identify a line item.
TransactionType:
type: string
description: Defines the type of payment lifecycle action.
enum:
- settle
- refund
example: settle
TotalAmount:
type: integer
example: 250
description: Implied decimal. For example, 250 GBP = £2.50.
ErrorResponse422:
type: object
required:
- errorName
- message
properties:
errorName:
type: string
enum:
- fieldIsMissing
- fieldHasInvalidValue
description: A machine and human readable error type for clarity and semantic understanding of the error.
example: fieldHasInvalidValue
message:
type: string
description: A human readable message giving a corrective action for the error. *This is not for machine consumption*.
ErrorResponse415:
type: object
required:
- errorName
- message
properties:
errorName:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-splitpayments-api-openapi.yml