# 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](/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-bsh.securedataplatform.com/payouts/{resource}"
        }
    },
    "curies": [
        {
            "name": "payouts",
            "href": "https://access.worldpay-bsh.securedataplatform.com/rels/payouts/{rel}",
            "templated": true
        }
    ]
}
```

After:


```
{
	"outcome": "approved",
	"receivedAt": "2023-09-01T10:37:36.923Z",
	"_links": {
		"payouts:payout": {
			"href": "https://access.worldpay-bsh.securedataplatform.com/payouts/{resource}"
		},
		"curies": [{
			"name": "payouts",
			"href": "https://access.worldpay-bsh.securedataplatform.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-bsh.securedataplatform.com/payouts/{resource}"
        },
        "payouts:update": {
            "href": "https://try.access.worldpay-bsh.securedataplatform.com/payouts/{resource}"
        },
        "curies": [{
            "name": "payouts",
            "href": "https://try.access.worldpay-bsh.securedataplatform.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-bsh.securedataplatform.com/payouts/{resource}"
        }
    },
    "curies": [
        {
            "name": "payouts",
            "href": "https://access.worldpay-bsh.securedataplatform.com/rels/payouts/{rel}",
            "templated": true
        }
    ]
}
```

After:


```
{
	"outcome": "requestReceived",
	"receivedAt": "2020-05-06T12:29:39.625884Z",
	"_links": {
		"payouts:payout": {
			"href": "https://access.worldpay-bsh.securedataplatform.com/payouts/{resource}"
		},
		"curies": [{
			"name": "payouts",
			"href": "https://access.worldpay-bsh.securedataplatform.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](/products/reference/worldpay-error-responses)
- [narrative](/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)

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

details
summary
More details
You can now submit a `preferredCardBrand` in your [Fast Access request](/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`](/products/card-payouts/payouts#possible-outcomes). You might receive this outcome if your card payout request is being reviewed for legal or compliance reasons.

#### 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](/products/card-payouts/payouts).

#### 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](/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](/products/card-payouts/v3/payouts) for the `payoutInstrument` `card/networkToken+applepay`.

#### 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-bsh.securedataplatform.com/payouts/{resource}"
        }
    },
    "curies": [
        {
            "name": "payouts",
            "href": "https://access.worldpay-bsh.securedataplatform.com/rels/payouts/{rel}",
            "templated": true
        }
    ]
}
```

After:


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

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

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

#### 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](/products/reference/formatting#narrative-format):

- abcdefghijklmnopqrstuvwxyz
- spaces