# Create split payments request

Create a request allowing you to split your payment.

Endpoint: POST /splitPayments
Version: 2025-06-25
Security: BasicAuth

## Security:

  - `BasicAuth` (unknown)
    http basic

## Header parameters:

  - `Content-Type` (string, required)
    The Content-Type.

  - `WP-Api-Version` (string, required)
    The API version.

## Request fields (application/json):

  - `reference` (string, required)
    A reference generated by you to identify the split payments.

  - `description` (string)
    Used to identify a split payment of an order to help with reconciliation purposes. When used, the values appear in the Payouts Portal.

  - `fulfillment` (object, required)

  - `fulfillment.auto` (boolean, required)
    Set to 'true' for auto fulfillment, otherwise to 'false'

  - `fulfillment.paymentCommandId` (string, 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](/products/card-payments/openapi/other/authorize#other/authorize/t=response&c=201&path=&d=0/commandid) in our Card Payments API.

  - `merchant` (object, required)

  - `merchant.entity` (string, required)
    Used to route the request in Access Worldpay, created as part of on-boarding.
    Example: default

  - `value` (object, required)

  - `value.currency` (string, required)
    The [3 letter ISO-4217 currency code](/products/reference/supported-countries-currencies#iso-currency-codes).
    Example: GBP

  - `value.totalAmount` (integer, required)
    Must be positive integer greater than 0. Implied decimal. For example, 250 GBP = £2.50.
    Example: 250

  - `lineItems` (array, required)

  - `lineItems.itemReference` (string, required)
    Unique reference generated by you to identify a line item.

  - `lineItems.partyReference` (string, required)
    Unique reference generated by you to identify a party.

  - `lineItems.amount` (integer, required)
    Must be positive integer greater than 0. Implied decimal. For example, 250 GBP = £2.50
    Example: 250

  - `lineItems.description` (string)
    Used to identify a split payment of an order to help with reconciliation purposes. When used, the values appear in the Payouts Portal.

  - `lineItems.deductions` (array)

  - `lineItems.deductions.type` (string, required)
    Type of deduction.
    Enum: "commission", "fee"

  - `lineItems.deductions.value` (object, required)

  - `lineItems.deductions.value.type` (string, required)
    Type of value.
    Enum: "percentage", "flat"

  - `lineItems.deductions.value.amount` (number, required)

  - `lineItems.deductions.value.type` (string, required)
    Enum: "percentage"

  - `lineItems.deductions.value.amount` (number, required)
    The deduction amount. Must be greater than 0.
When type is percentage, decimal values are permitted, and the value must not exceed 100. For example, 7.5 represents 7.5%.

  - `lineItems.deductions.value.amount` (integer, required)
    The deduction amount. Must be greater than 0.
When type is flat, the value must be a whole number and represents a monetary amount with an implied decimal. For example, 250 GBP = £2.50.

  - `lineItems.deductions.description` (string)
    Used to identify a split payment of an order to help with reconciliation purposes. When used, the values appear in the Payouts Portal.
    Example: Deduction description

## Request examples:

  - `SplitPayment` (unknown)
    Example request for creating a split payment

## Response 201:

  - `201` (unknown)
    Merchant Pay-in accepted

## Response 201 fields (application/json):

  - `splitPaymentId` (string, required)
    Unique reference generated by us to identify a split payment.

  - `lineItems` (object, required)

  - `lineItems.items` (array)

  - `lineItems.items.itemId` (string, required)
    Unique reference generated by us to identify a line item.

  - `lineItems.items.itemReference` (string, required)
    Unique reference generated by you to identify a line item.

## Response 201 headers (application/json):

  - `WP-CorrelationId` (string)
    Example: c85762a8-93af-47e7-beae-345d3dddbe94

## Response 400:

  - `400` (unknown)
    Bad request format or data

## Response 400 fields (application/json):

  - `errorName` (string, required)
    Enum: "bodyIsEmpty", "bodyIsNotJson", "bodyDoesNotMatchSchema"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

  - `validationErrors` (array)
    If there were field validation errors, they will be collected in this array.

  - `validationErrors.errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "fieldIsNull", "fieldIsEmpty", "numberIsTooLarge", "numberIsTooSmall", "stringFailedRegexCheck"

  - `validationErrors.message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

  - `validationErrors.jsonPath` (string, required)
    The field presents the JSONPath of the element within the request body associated with the error.

## Response 400 headers (application/json):

  - `WP-CorrelationId` (string)
    Example: c85762a8-93af-47e7-beae-345d3dddbe94

## Response 401:

  - `401` (unknown)
    Un-authorized access, Insufficient permissions to fulfil request.

## Response 401 fields (application/json):

  - `errorName` (string, required)
    Un-authorized access, Insufficient permissions to fulfil request.
    Enum: "unauthorizedAccess"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

## Response 401 headers (application/json):

  - `WP-CorrelationId` (string)
    Example: c85762a8-93af-47e7-beae-345d3dddbe94

## Response 406:

  - `406` (unknown)
    A request header or API version value is invalid or unsupported.

## Response 406 fields (application/json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "headerHasInvalidValue"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

## Response 406 headers (application/json):

  - `WP-CorrelationId` (string)
    Example: c85762a8-93af-47e7-beae-345d3dddbe94

## Response 415:

  - `415` (unknown)
    Media type not supported

## Response 415 fields (application/json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "headerHasInvalidValue"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

## Response 415 headers (application/json):

  - `WP-CorrelationId` (string)
    Example: c85762a8-93af-47e7-beae-345d3dddbe94

## Response 422:

  - `422` (unknown)
    Wrong party info, or no balanceAccount

## Response 422 fields (application/json):

  - `errorName` (string, required)
    A machine and human readable error type for clarity and semantic understanding of the error.
    Enum: "invalidPartyState"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

  - `stateErrors` (array, required)
    Details of each invalid party state found in the request.

  - `stateErrors.errorName` (string, required)
    A machine-readable error code for the specific party state validation failure.
    Example: referenceNotFound

  - `stateErrors.message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

  - `stateErrors.path` (string)
    JSON path to the party reference or party ID that failed validation.

  - `stateErrors.url` (string)
    URL containing additional context about the failure.

## Response 422 headers (application/json):

  - `WP-CorrelationId` (string)
    Example: c85762a8-93af-47e7-beae-345d3dddbe94

## Response 500:

  - `500` (unknown)
    internalErrorOccurred

## Response 500 fields (application/json):

  - `errorName` (string, required)
    An error occurred within the service.
    Enum: "internalErrorOccurred"

  - `message` (string, required)
    A human readable message giving a corrective action for the error.  *This is not for machine consumption*.

## Response 500 headers (application/json):

  - `WP-CorrelationId` (string)
    Example: c85762a8-93af-47e7-beae-345d3dddbe94

## Response 201 examples:

  - `Purchase` (unknown)

## Response 400 examples:

  - `bodyIsEmpty` (unknown)

  - `bodyIsNotJson` (unknown)

  - `bodyDoesNotMatchSchema` (unknown)

## Response 401 examples:

  - `unauthorizedAccess` (unknown)

## Response 406 examples:

  - `invalidAcceptHeader` (unknown)

  - `invalidApiVersionHeader` (unknown)

## Response 415 examples:

  - `headerHasInvalidValue` (unknown)

## Response 422 examples:

  - `invalidPartyState` (unknown)

## Response 500 examples:

  - `Internal server error` (unknown)