APIs
/
Split Payments
/
Fully settle/refund a purchase

Split Payments (2024-10-10)

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

Authentication Set your headers

    Authorization: {your_credentials}
    WP-Api-Version: 2024-10-10

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 purchase request

Request

Create a purchase 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: 2024-10-10
WP-Timestampstring(date-time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|:\d{2}...required

Timestamp of this request per RFC3339 section 5.6

Examples:
2020-07-28T16:15:48Z
2020-07-28T16:15:48:00:00
Bodyapplication/jsonrequired
purchaseReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

Reference for the purchase generated by you.

fulfillmentobjectrequired
autobooleanrequired

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

commandIdstring= 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.

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

Command reference generated by you.

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"
narrativeobject

The text that appears on your customer's statement.

line1string[ 3 .. 21 ] characters^[a-zA-Z0-9 ,./-]*$required

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.

line2string[ 3 .. 21 ] characters^[a-zA-Z0-9 ,./-]*$

Additional text to appear on the customer's billing statement.

valueobjectrequired
currencystring^[A-Z]{3}$required

The 3 letter ISO-4217 currency code.

Example: "USD"
totalAmountintegerrequired

Implied decimal. For example, 250 USD = $2.50.

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

Unique reference generated by you to identify a purchase item.

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

Unique reference generated by you to identify a party.

amountintegerrequired

Implied decimal. For example, 250 USD = $2.50

Example: 250
narrativeobject

The text that appears on your customer's statement.

commissionobject
feeobject
application/json

For every purchase you can define how you want to split the funds between the number of entities that belong to yourself and the beneficiaries on your platform

{
  "purchaseReference": "5D262CB9-57F2-4176-AA7C-B76A79284277",
  "fulfillment": {
    "auto": false,
    "commandId": "cmdJxsTja3Daad6dig338w2R0",
    "commandReference": "5D262CB9-57F2-4176-AA7C-B76A79284276"
  },
  "merchant": {
    "entity": "default"
  },
  "narrative": {
    "line1": "Socks",
    "line2": "Sandals"
  },
  "value": {
    "currency": "GBP",
    "totalAmount": 50
  },
  "items": [
    {
      "itemReference": "aaa1",
      "partyReference": "Sherlock Holmes",
      "amount": 30,
      "narrative": {
        "line1": "Socks"
      },
      "commission": {
        "narrative": {
          "line1": "Socks"
        },
        "amount": 3
      },
      "fee": {
        "narrative": {
          "line1": "Socks"
        },
        "amount": 2
      }
    },
    {
      "itemReference": "bbb1",
      "partyReference": "John Watson",
      "amount": 20,
      "narrative": {
        "line1": "Sandals"
      },
      "commission": {
        "narrative": {
          "line1": "Sandals"
        },
        "amount": 3
      },
      "fee": {
        "narrative": {
          "line1": "Sandals"
        },
        "amount": 2
      }
    }
  ]
}

Responses

Merchant Pay-in accepted

Bodyapplication/json
purchaseIdstring= 25 characters^pur[A-Za-z0-9_-]{21}0$required

Unique reference generated by us to identify a purchase.

purchaseobjectrequired
itemsArray of objectsrequired
Response
application/json
{
  "purchaseId": "purd1dcd2dee333cae1bfdea0",
  "purchase": {
    "items": [
      {
        "itemId": "itmd1dcd2dee333cae1bfded0",
        "itemReference": "aaa1"
      }
    ]
  }
}

Fully settle/refund a purchase

Request

Confirm a settlement/refund of all line items within a purchase.

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

ID of the purchase

Example: purd1dcd2dee333cae1bfdea0
Headers
Content-Typestringrequired

The Content-Type

Example: application/json
WP-Api-Versionstringrequired

The API version

Example: 2024-10-10
WP-Timestampstring(date-time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|:\d{2}...required

Timestamp of this request per RFC3339 section 5.6

Examples:
2020-07-28T16:15:48Z
2020-07-28T16:15:48:00:00
Authorizationstring(Basic <base64-encoded 'user:password'>)required
Example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQK
Bodyapplication/jsonrequired
commandIdstring= 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.

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

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

transactionTypestringrequired

For Settle or Refund?

Enum"Settle""Refund"
Example: "Settle"
narrativeobject

The text that appears on your customer's statement.

line1string[ 3 .. 21 ] characters^[a-zA-Z0-9 ,./-]*$required

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.

line2string[ 3 .. 21 ] characters^[a-zA-Z0-9 ,./-]*$

Additional text to appear on the customer's billing statement.

application/json

Register a command ID for a full capture

{
  "commandId": "cmdyv_5QNY5uuwsm-6HlE1f80",
  "commandReference": "5D262CB9-57F2-4176-AA7C-B76A79284276",
  "transactionType": "Settle",
  "narrative": {
    "line1": "Socks",
    "line2": "Sandals"
  }
}

Responses

Merchant Pay-in accepted

Bodyapplication/json
fulfillmentsstring
Response
application/json
{
  "fulfillments": "Accepted"
}

Partially settle/refund an item

Request

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

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

ID of the purchase

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

ID of the purchase item listed in a purchase request

Headers
Content-Typestringrequired

The Content-Type

Example: application/json
WP-Api-Versionstringrequired

The API version

Example: 2024-10-10
WP-Timestampstring(date-time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|:\d{2}...required

Timestamp of this request per RFC3339 section 5.6

Examples:
2020-07-28T16:15:48Z
2020-07-28T16:15:48:00:00
Authorizationstring(Basic <base64-encoded 'user:password'>)required
Example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQK
Bodyapplication/jsonrequired
commandIdstring= 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.

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

Command reference generated by you.

transactionTypestringrequired

For Settle or Refund?

Enum"Settle""Refund"
Example: "Settle"
narrativeobject

The text that appears on your customer's statement.

line1string[ 3 .. 21 ] characters^[a-zA-Z0-9 ,./-]*$required

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.

line2string[ 3 .. 21 ] characters^[a-zA-Z0-9 ,./-]*$

Additional text to appear on the customer's billing statement.

application/json

Register a command ID for a partial capture/single item

{
  "commandId": "cmdWYl_hJt7N2Yw7d-Lpp2oi0",
  "commandReference": "5D262CB9-57F2-4176-AA7C-B76A79284276",
  "transactionType": "Settle",
  "narrative": {
    "line1": "Socks"
  }
}

Responses

Merchant Pay-in accepted

Bodyapplication/json
fulfillmentsstring
Response
application/json
{
  "fulfillments": "Accepted"
}