{
"openapi": "3.1.0",
"info": {
"title": "Split Payments",
"description": "Divide funds from a single payment amongst yourself and your parties/sellers.\n\n\n __Authentication__\n Set your headers\n```\n Authorization: {your_credentials}\n WP-Api-Version: 2025-06-25\n```\n Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n
\n __DNS whitelisting__\n\n Whitelist the following URLs:\n * `https://try.access.worldpay-bsh.securedataplatform.co.uk/`\n * `https://access.worldpay-bsh.securedataplatform.co.uk/`\n\n Please ensure you use DNS whitelisting, not explicit IP whitelisting.\n When you make a request within Access Worldpay, you should always cache the response returned.\n ",
"version": "2025-06-25",
"x-metadata": {
"business": [
"Enterprise",
"Marketplaces"
],
"catalog-list": true,
"category": [
"Card Payments"
],
"generated": true
}
},
"servers": [
{
"url": "https://try.access.worldpay-bsh.securedataplatform.co.uk",
"description": "Test (Try)"
},
{
"url": "https://access.worldpay-bsh.securedataplatform.co.uk",
"description": "Live"
}
],
"security": [
{
"BasicAuth": []
}
],
"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"
}
}
}
}
},
"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/ErrorResponseWithSplitValidationErrors"
},
"examples": {
"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"
}
}
}
}
},
"406": {
"description": "A request header or API version value is invalid or unsupported.",
"headers": {
"WP-CorrelationId": {
"example": "c85762a8-93af-47e7-beae-345d3dddbe94",
"schema": {
"type": "string",
"format": "uuid"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse406"
},
"examples": {
"invalidAcceptHeader": {
"$ref": "#/components/examples/406_accept"
},
"invalidApiVersionHeader": {
"$ref": "#/components/examples/406_api_version"
}
}
}
}
},
"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": {
"invalidPartyState": {
"$ref": "#/components/examples/422-invalidPartyState"
}
}
}
}
},
"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"
}
},
"/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"
}
}
}
}
},
"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": {
"bodyIsEmpty": {
"$ref": "#/components/examples/400-bodyIsEmpty"
},
"bodyIsNotJson": {
"$ref": "#/components/examples/400-bodyIsNotJson"
},
"bodyDoesNotMatchSchema": {
"$ref": "#/components/examples/400-bodyDoesNotMatchSchema"
},
"urlContainsInvalidValue": {
"$ref": "#/components/examples/400-urlContainsInvalidValue_splitId"
}
}
}
}
},
"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"
}
}
}
}
},
"406": {
"description": "A request header or API version value is invalid or unsupported.",
"headers": {
"WP-CorrelationId": {
"example": "c85762a8-93af-47e7-beae-345d3dddbe94",
"schema": {
"type": "string",
"format": "uuid"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse406"
},
"examples": {
"invalidAcceptHeader": {
"$ref": "#/components/examples/406_accept"
},
"invalidApiVersionHeader": {
"$ref": "#/components/examples/406_api_version"
}
}
}
}
},
"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"
}
},
"/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"
}
}
}
}
},
"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": {
"bodyIsEmpty": {
"$ref": "#/components/examples/400-bodyIsEmpty"
},
"bodyIsNotJson": {
"$ref": "#/components/examples/400-bodyIsNotJson"
},
"bodyDoesNotMatchSchema": {
"$ref": "#/components/examples/400-bodyDoesNotMatchSchema"
},
"urlContainsInvalidValue": {
"$ref": "#/components/examples/400-urlContainsInvalidValue_splitId_and_itemId"
}
}
}
}
},
"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"
}
}
}
}
},
"406": {
"description": "A request header or API version value is invalid or unsupported.",
"headers": {
"WP-CorrelationId": {
"example": "c85762a8-93af-47e7-beae-345d3dddbe94",
"schema": {
"type": "string",
"format": "uuid"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse406"
},
"examples": {
"invalidAcceptHeader": {
"$ref": "#/components/examples/406_accept"
},
"invalidApiVersionHeader": {
"$ref": "#/components/examples/406_api_version"
}
}
}
}
},
"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"
}
}
},
"components": {
"schemas": {
"SplitRequest": {
"required": [
"reference",
"fulfillment",
"merchant",
"value",
"lineItems"
],
"properties": {
"reference": {
"maxLength": 64,
"minLength": 1,
"type": "string",
"pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\\\[\\\\]{}~`/+]+$",
"description": "A reference generated by you to identify the split payments."
},
"description": {
"maxLength": 50,
"pattern": "^[a-zA-Z0-9 ,./-]*$",
"type": "string",
"description": "Used to identify a split payment of an order to help with reconciliation purposes. When used, the values appear in the Payouts Portal."
},
"fulfillment": {
"$ref": "#/components/schemas/AutoFulfillment"
},
"merchant": {
"$ref": "#/components/schemas/Merchant"
},
"value": {
"$ref": "#/components/schemas/Value"
},
"lineItems": {
"$ref": "#/components/schemas/LineItems"
}
}
},
"SplitResponse": {
"type": "object",
"required": [
"splitPaymentId",
"lineItems"
],
"properties": {
"splitPaymentId": {
"$ref": "#/components/schemas/SplitPaymentID"
},
"lineItems": {
"$ref": "#/components/schemas/SplitResp"
}
}
},
"FulfillmentsRequest": {
"required": [
"reference",
"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 the split payments."
},
"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"
}
}
},
"FulfillmentsResponse": {
"type": "object",
"properties": {
"fulfillment": {
"type": "string",
"description": "Update status to fulfilled"
}
}
},
"ItemFulfillmentsRequest": {
"required": [
"reference",
"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 the split payments."
},
"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"
}
}
},
"ItemFulfillmentsResponse": {
"type": "object",
"properties": {
"fulfillment": {
"type": "string",
"description": "Update status to fulfilled"
}
}
},
"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"
}
}
},
"SplitResp": {
"type": "object",
"properties": {
"items": {
"$ref": "#/components/schemas/LineItemsResp"
}
}
},
"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"
}
}
},
"Value": {
"required": [
"currency",
"totalAmount"
],
"type": "object",
"properties": {
"currency": {
"$ref": "#/components/schemas/Currency"
},
"totalAmount": {
"$ref": "#/components/schemas/TotalAmount"
}
}
},
"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,
"minimum": 1,
"description": "Must be positive integer greater than 0. Implied decimal. For example, 250 GBP = £2.50."
},
"Amount": {
"type": "integer",
"example": 250,
"minimum": 1,
"description": "Must be positive integer greater than 0. Implied decimal. For example, 250 GBP = £2.50"
},
"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$"
},
"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$"
},
"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$"
},
"TransactionType": {
"type": "string",
"description": "Defines the type of payment lifecycle action.",
"enum": [
"settle",
"refund"
],
"example": "settle"
},
"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": "number",
"exclusiveMinimum": 0,
"examples": [
7.5,
250
]
}
},
"oneOf": [
{
"title": "percentage",
"type": "object",
"required": [
"type",
"amount"
],
"properties": {
"type": {
"type": "string",
"enum": [
"percentage"
]
},
"amount": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 100,
"description": "The deduction amount. Must be greater than 0.\nWhen type is percentage, decimal values are permitted, and the value must not exceed 100. For example, 7.5 represents 7.5%."
}
}
},
{
"title": "flat",
"type": "object",
"required": [
"type",
"amount"
],
"properties": {
"type": {
"type": "string",
"enum": [
"flat"
]
},
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "The deduction amount. Must be greater than 0.\nWhen 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."
}
}
}
]
},
"description": {
"pattern": "^[a-zA-Z0-9 ,./-]*$",
"type": "string",
"maxLength": 50,
"description": "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"
}
}
}
},
"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,
"pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\\\[\\\\]{}~`/+]+$",
"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": "Used to identify a split payment of an order to help with reconciliation purposes. When used, the values appear in the Payouts Portal."
},
"deductions": {
"$ref": "#/components/schemas/Deductions"
}
}
}
},
"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."
}
}
}
},
"ErrorResponse401": {
"required": [
"errorName",
"message"
],
"type": "object",
"properties": {
"errorName": {
"type": "string",
"enum": [
"unauthorizedAccess"
],
"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*."
}
}
},
"ErrorResponse406": {
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"enum": [
"headerHasInvalidValue"
],
"description": "A machine and human readable error type for clarity and semantic understanding of the error."
},
"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": {
"type": "string",
"enum": [
"headerHasInvalidValue"
],
"description": "A machine and human readable error type for clarity and semantic understanding of the error."
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*."
}
}
},
"ErrorResponse422": {
"type": "object",
"required": [
"errorName",
"message",
"stateErrors"
],
"properties": {
"errorName": {
"type": "string",
"enum": [
"invalidPartyState"
],
"description": "A machine and human readable error type for clarity and semantic understanding of the error."
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*."
},
"stateErrors": {
"type": "array",
"description": "Details of each invalid party state found in the request.",
"items": {
"$ref": "#/components/schemas/StateError"
}
}
}
},
"StateError": {
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"example": "referenceNotFound",
"description": "A machine-readable error code for the specific party state validation failure."
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*."
},
"path": {
"type": "string",
"description": "JSON path to the party reference or party ID that failed validation."
},
"url": {
"type": "string",
"description": "URL containing additional context about the failure."
}
}
},
"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*."
}
}
},
"ErrorResponseWithSplitValidationErrors": {
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"enum": [
"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/SplitValidationError"
}
}
}
},
"ErrorResponseWithValidationErrors": {
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"enum": [
"bodyIsEmpty",
"bodyIsNotJson",
"bodyDoesNotMatchSchema",
"urlContainsInvalidValue"
]
},
"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"
}
}
}
},
"SplitValidationError": {
"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 the element within the request body associated with the error."
}
}
},
"ValidationError": {
"required": [
"errorName",
"message"
],
"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 the element within the request body associated with the error."
},
"queryParameter": {
"type": "string",
"description": "The query parameter associated with the validation error."
},
"pathParameter": {
"type": "string",
"description": "The path parameter associated with the validation error."
}
}
}
},
"securitySchemes": {
"BasicAuth": {
"type": "http",
"scheme": "basic"
}
},
"examples": {
"415": {
"value": {
"errorName": "headerHasInvalidValue",
"message": "A header 'Content-Type' in the request does not contain an expected value. Content-type must be application/json"
}
},
"500": {
"value": {
"errorName": "internalErrorOccurred",
"message": "An error occurred within the service."
}
},
"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"
}
]
}
]
}
},
"split-201": {
"value": {
"splitPaymentId": "spl9wdyDYROy6-boa2mSFfn20",
"lineItems": [
{
"itemId": "itmZRsCU4vjopY6q9HH9znXQ0",
"itemReference": "aaa1"
},
{
"itemId": "itmO9IHhLjjamTh9oHcR1wH-0",
"itemReference": "bbb1"
}
]
}
},
"400-bodyIsEmpty": {
"value": {
"errorName": "bodyIsEmpty",
"message": "The body within the request is empty. A body is required to be non-empty."
}
},
"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."
}
},
"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": "$.reference"
},
{
"errorName": "fieldIsEmpty",
"message": "must not be blank",
"jsonPath": "$.paymentCommandId"
}
]
}
},
"401-unauthorizedAccess": {
"value": {
"errorName": "unauthorizedAccess",
"message": "The provided secret does not contain valid authentication."
}
},
"406_accept": {
"value": {
"errorName": "headerHasInvalidValue",
"message": "A header 'Accept' in the request does not contain an expected pattern. It must be application/json, or not set."
}
},
"406_api_version": {
"value": {
"errorName": "headerHasInvalidValue",
"message": "A header 'WP-Api-Version' or URL path in the request is misconfigured."
}
},
"422-invalidPartyState": {
"value": {
"errorName": "invalidPartyState",
"message": "One or more parties are in an invalid state.",
"stateErrors": [
{
"errorName": "referenceNotFound",
"message": "Reference badBeneficiary was not found",
"path": "$.parties.refs[1]",
"url": "https://url.com"
},
{
"errorName": "partyIdNotFound",
"message": "PartyId par_V1StGXR8_Z5jdHi6B-myF was not found",
"path": "$.parties.ids[3]",
"url": "https://url.com"
}
]
}
},
"FulfillmentsRequest": {
"value": {
"reference": "5D262CB9-57F2-4176-AA7C-B76A79284276",
"description": "optional description of fulfillment",
"paymentCommandId": "cmdJxsTja3Daad6dig338w2R0",
"transactionType": "settle"
}
},
"RefundRequest": {
"value": {
"reference": "5D262CB9-57F2-4176-AA7C-B76A79284276",
"description": "optional description of fulfillment",
"paymentCommandId": "cmdJxsTja3Daad6dig338w2R0",
"transactionType": "refund"
}
},
"fulfillments-201": {
"value": {
"fulfillment": "accepted"
}
},
"400-urlContainsInvalidValue_splitId": {
"value": {
"errorName": "urlContainsInvalidValue",
"message": "The URL contains a value or values that are invalid.",
"validationErrors": [
{
"errorName": "invalidUrlPathParameter",
"message": "The URL field 'splitPaymentId' has an invalid value: 'spld1dcd2dee333cae1bfdea0'.",
"pathParameter": "splitPaymentId"
}
]
}
},
"FulfillmentRequestSingle": {
"value": {
"reference": "5D262CB9-57F2-4176-AA7C-B76A79284276",
"description": "optional description of fulfillment",
"paymentCommandId": "cmdJxsTja3Daad6dig338w2R0",
"transactionType": "settle"
}
},
"400-urlContainsInvalidValue_splitId_and_itemId": {
"value": {
"errorName": "urlContainsInvalidValue",
"message": "The URL contains a value or values that are invalid.",
"validationErrors": [
{
"errorName": "invalidUrlPathParameter",
"message": "The URL field 'splitPaymentId' has an invalid value: 'spld1dcd2dee333cae1bfdea0'.",
"pathParameter": "splitPaymentId"
},
{
"errorName": "invalidUrlPathParameter",
"message": "The URL field 'itemId' has an invalid value: 'itmZRsCU4vjopY6q9HH9znXQ0'.",
"pathParameter": "itemId"
}
]
}
}
}
}
}