# 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](/access/products/reference/api-principles) to ensure a resilient integration.

## Versioning log

### Version 4 (11 September 2023)

details
summary
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 clearer.

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)

details
summary
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)

details
summary
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](/access/products/reference/worldpay-error-responses)
- [narrative](/access/products/reference/formatting#narrative-format) now has two lines in the JSON block:


Before:


```
"narrative": "abc"
```

After: 


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

## Change log (non-breaking changes)

#### New Fast Access fallback to basic disbursements option (06 March 2026)

details
summary
More details
You can now submit a `fallbackToBasic` option in your [Fast Access request](/access/products/card-payouts/payouts#routing-your-fast-access-request). This allows you to specify whether the Fast Access payout request should automatically fall back to basic disbursements or not where there is no response from the card scheme.

details
summary
2025
#### Fast Access preferred card brand support (08 October 2025)

details
summary
More details
You can now submit a `preferredCardBrand` in your [Fast Access request](/access/products/card-payouts/payouts#routing-your-fast-access-request). This allows you to request that your card payout is routed to your preferred card scheme (currently Maestro/Mastercard only).

We have also added a new [`outcome` of `inReview`](/access/products/card-payouts/payouts#possible-outcomes). You might receive this outcome if your card payout request is being reviewed for legal or compliance reasons.

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

details
summary
More details
You can now use the `card/networkToken` paymentInstrument in your [payout request](/access/products/card-payouts/payouts).

details
summary
2021
#### Card expiry validation removal (v3) (25 May 2021)

details
summary
More details
The `cardExpiry` can now be a date in the past for your [`basicDisbursement` request](/access/products/card-payouts/v3/payouts#standard-payout) which allows you to process unreferenced refunds.

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

details
summary
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)

details
summary
More details
You can now request a [Payout](/access/products/card-payouts/v3/payouts) for the `payoutInstrument` `card/networkToken+applepay`.

details
summary
2020
#### Updated merchant response (v2) (11 May 2020)

details
summary
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
	}]
}
```

#### Additional action link (v2) (07 February 2020)

details
summary
More details
When [querying the root resource](/access/products/card-payouts/v3/get-started#query-the-payouts-root-resource), you are now receiving the `payouts:query` action link.

details
summary
2019
#### Update resource timeout error message (v2) (31 December 2019)

details
summary
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)

details
summary
More details
The following characters are now allowed for [narrative](/access/products/reference/formatting#narrative-format):

- abcdefghijklmnopqrstuvwxyz
- spaces