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

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.

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:

UTC 2020-07-28T16:15:48Z

TZ-Offset 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.

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:

UTC 2020-07-28T16:15:48Z

TZ-Offset 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

{
  "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.

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:

UTC 2020-07-28T16:15:48Z

TZ-Offset 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

{
  "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"
}

Split Payments (2024-10-10)

Create purchase request

Request

Responses

Do you like our page?

Fully settle/refund a purchase

Request

Responses

Do you like our page?

Partially settle/refund an item

Request

Responses

Do you like our page?

Split Payments (2024-10-10)

Create purchase request

RequestExpand all

Responses

Do you like our page?

Fully settle/refund a purchase

RequestExpand all

Responses

Do you like our page?

Partially settle/refund an item

RequestExpand all

Responses

Do you like our page?

Request

Request

Request