New service | **Last updated**: 01 July 2025

# Split a payment

### Example use case

This example outlines a split payment journey within a food delivery marketplace platform. Ensuring a seamless experience for customer, restaurant and driver.

**Scenario:** A customer orders a food delivery from a local restaurant, the Baker Street Café, to their home.

1. **Order placement:** Customer makes food order for £100.
2. **Order acceptance and delivery:** Restaurant accepts order and sends food via delivery driver.
3. **Payment distribution:** The food delivery marketplace splits the `"totalAmount": 10000` as follows:
  * **restaurant:** `"amount": 9000`, with a `commission` of 1% being taken by the food delivery marketplace. The marketplace therefore receives £0.10 in their virtual Worldpay bank account, leaving £89.10 to be paid out to `partyReference: "The Baker Street Café"`
  * **delivery driver:** `"amount": 1000`, with a `fee` of £2 being taken by the food delivery marketplace, which they will receive in their virtual Worldpay bank account. Leaving £8 to be paid out to `"partyReference": John Watson"`


## Request

Best Practice
Only split a payment once you have submitted the final amount to be authorized.

`POST` `https://try.access.worldpay-bsh.securedataplatform.com/splitPayments`

#### Request examples

#### Request schema


```json
{
  "$ref": "#/components/schemas/SplitRequest",
  "components": {
    "schemas": {
      "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$"
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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}$"
      },
      "TotalAmount": {
        "type": "integer",
        "example": 250,
        "description": "Implied decimal. For example, 250 GBP = £2.50."
      },
      "Value": {
        "required": [
          "currency",
          "totalAmount"
        ],
        "type": "object",
        "properties": {
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "totalAmount": {
            "$ref": "#/components/schemas/TotalAmount"
          }
        }
      },
      "Amount": {
        "type": "integer",
        "example": 250,
        "description": "Implied decimal. For example, 250 GBP = £2.50"
      },
      "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"
            }
          }
        }
      },
      "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"
            }
          }
        }
      },
      "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"
          }
        }
      }
    }
  }
}
```

### Deductions

Optional commissions and fees are deducted per `lineItem`.

In the [above example](#request-examples) where `"itemReference"="aaa1"` and the `"amount": 90`, a `commission` of 1% is taken against the £90. Leaving £89.10 to be paid out to `"partyReference": "The Baker Street Café"`.

There is also a second deduction taken against `"itemReference"="bbb2"` with `"amount": 10`. In the request a flat `fee` of £2 is taken. The remainder of £8 will be paid out to `"partyReference": "John Watson"`

#### Example extract


```
"deductions": [
        {
          "type": "commission",
          "value": {
            "type": "percentage",
            "amount": 1
          },
          "description": "Deduction description"
        }
```

View our full request and response schema in our [API reference](/products/split-payments/openapi).

## Response

#### Example response

#### Response schema


```json
{
  "$ref": "#/components/schemas/SplitResponse",
  "components": {
    "schemas": {
      "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$"
      },
      "ItemID": {
        "type": "string",
        "description": "Unique reference generated by us to identify a line item.",
        "minLength": 25,
        "maxLength": 25,
        "pattern": "^itm[A-Za-z0-9_-]{21}0$"
      },
      "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."
            }
          }
        }
      },
      "SplitResp": {
        "type": "object",
        "properties": {
          "items": {
            "$ref": "#/components/schemas/LineItemsResp"
          }
        }
      },
      "SplitResponse": {
        "type": "object",
        "required": [
          "splitPaymentId",
          "lineItems"
        ],
        "properties": {
          "splitPaymentId": {
            "$ref": "#/components/schemas/SplitPaymentID"
          },
          "lineItems": {
            "$ref": "#/components/schemas/SplitResp"
          }
        }
      }
    }
  }
}
```

#### Errors

Check out our API reference for the full [error code schema](/products/split-payments/openapi/other/splitpayments#other/splitpayments/response&c=201).

Note
If you have set `fulfillment.auto` to `false` you **must** now settle your payment.

**Next steps**

[Settle your purchase](/products/split-payments/manage)
[Refund your purchase](/products/split-payments/manage#refund-a-payment)