Access Worldpay
/
Versioning and Change log

Versioning and Change log

This log details any breaking and non-breaking API changes we have released for our Payouts service.

Prerequisite

Make yourself familiar with our API Principles to ensure a resilient integration.

Versioning log

Version 4 (11 September 2023)

Mastercard Send and queryRequired outcome removal

Version 4 introduces Mastercard Send, enabling you to send funds directly to a customer's bank account within 30 minutes or less using the fastAccess endpoint. This change introduces updates to the response for Mastercard fastAccess requests.

Before:

{
    "outcome": "requestReceived",
    "receivedAt": "2023-09-01T10:37:36.923Z",
    "_links": {
        "payouts:payout": {
            "href": "https://access.worldpay.com/payouts/{resource}"
        }
    },
    "curies": [
        {
            "name": "payouts",
            "href": "https://access.worldpay.com/rels/payouts/{rel}",
            "templated": true
        }
    ]
}

After:

{
	"outcome": "approved",
	"receivedAt": "2023-09-01T10:37:36.923Z",
	"_links": {
		"payouts:payout": {
			"href": "https://access.worldpay.com/payouts/{resource}"
		},
		"curies": [{
			"name": "payouts",
			"href": "https://access.worldpay.com/rels/payouts/{rel}",
			"templated": true
		}]
	}
}

Additionally, Version 4 removes queryRequired as an outcome so that the next actions for an inconclusive Payout are more clear.

Before:

{
    "outcome": "queryRequired",
    "receivedAt": "2023-09-01T10:37:36.923Z",
    "_links": {
        "payouts:payout": {
            "href": "https://try.access.worldpay.com/payouts/{resource}"
        },
        "payouts:update": {
            "href": "https://try.access.worldpay.com/payouts/{resource}"
        },
        "curies": [{
            "name": "payouts",
            "href": "https://try.access.worldpay.com/rels/payouts/{rel}",
            "templated": true
        }]
    }
}

After:

{
    "errorName": "checkOutcome",
    "message": "We cannot guarantee that a resource was created. Please use the query endpoint to retrieve the outcome of this request. Resources may take several minutes to propagate."
}

Version 3 (11 May 2020)

Updated merchant response
  • The curies array block now only lives inside the _links JSON block

Before:

{
    "outcome": "requestReceived",
    "receivedAt": "2020-05-06T12:29:39.625884Z",
    "_links": {
        "payouts:payout": {
            "href": "https://access.worldpay.com/payouts/{resource}"
        }
    },
    "curies": [
        {
            "name": "payouts",
            "href": "https://access.worldpay.com/rels/payouts/{rel}",
            "templated": true
        }
    ]
}

After:

{
	"outcome": "requestReceived",
	"receivedAt": "2020-05-06T12:29:39.625884Z",
	"_links": {
		"payouts:payout": {
			"href": "https://access.worldpay.com/payouts/{resource}"
		},
		"curies": [{
			"name": "payouts",
			"href": "https://access.worldpay.com/rels/payouts/{rel}",
			"templated": true
		}]
	}
}

Version 2 (18 October 2019)

Strict parsing
  • header change to "Content-Type: application/vnd.worldpay.payouts-v2+json"
  • narrative max length has been reduced from 25 to 24
  • sending any fields not recorded in our documentation will return an error
  • narrative now has two lines in the JSON block:

Before:

"narrative": "abc"

After: 

"narrative": {
      "line1": "abc",
      "line2": "abc"
    }

Change log (Non-breaking changes)

Network Token support (v2,v3 and v4) (29 August 2024)

More details

You can now use the card/networkToken paymentInstrument in your payout request.

Card expiry validation removal (v3) (25 May 2021)

More details

The cardExpiry can now be a date in the past for your basicDisbursement request which allows you to process unreferenced refunds.

Cardholder name is now an optional field (v2 + v3) (11 March 2021)

More details

The payoutInstrument.cardHolderName field is no longer mandatory in v2 and v3 Payout requests.

Payouts for Apple Pay decrypted (v2 + v3) (27 January 2021)

More details

You can now request a Payout for the payoutInstrument card/networkToken+applepay.

Updated merchant response (v2) (11 May 2020)

More details

The curies array block has been updated to live inside the _links JSON block as well as outside.

Before:

{
    "outcome": "requestReceived",
    "receivedAt": "2020-05-06T12:29:39.625884Z",
    "_links": {
        "payouts:payout": {
            "href": "https://access.worldpay.com/payouts/{resource}"
        }
    },
    "curies": [
        {
            "name": "payouts",
            "href": "https://access.worldpay.com/rels/payouts/{rel}",
            "templated": true
        }
    ]
}

After:

{
	"outcome": "requestReceived",
	"receivedAt": "2020-05-06T12:29:39.625884Z",
	"_links": {
		"payouts:payout": {
			"href": "https://access.worldpay.com/payouts/{resource}"
		},
		"curies": [{
			"name": "payouts",
			"href": "https://access.worldpay.com/rels/payouts/{rel}",
			"templated": true
		}]
	},
	"curies": [{
		"name": "payouts",
		"href": "https://access.worldpay.com/rels/payouts/{rel}",
		"templated": true
	}]
}
More details

When querying the root resource, you are now receiving the payouts:query action link.

Update resource timeout error message (v2) (31 December 2019)

More details

Before:

{
   "outcome":"payoutNotFound",
   "message":"The payout does not exist, money has not been moved. Please try the payout again."
}

After:

{
   "outcome":"payoutNotFound",
   "message":"Your payout request was unsuccessful. Please retry."
}

Formatting update for payout narrative (v2) (20 November 2019)

More details

The following characters are now allowed for narrative:

  • abcdefghijklmnopqrstuvwxyz
  • spaces