This log details any breaking and non-breaking API changes we have released for our Payouts service.
Make yourself familiar with our API principles to ensure a resilient integration.
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."
}Updated merchant response
- The curies array block now only lives inside the
_linksJSON 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
}]
}
}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"
}More details
You can now submit a preferredCardBrand in 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. You might receive this outcome if your card payout request is being reviewed for legal or compliance reasons.
More details
You can now use the card/networkToken paymentInstrument in your payout request.
More details
The cardExpiry can now be a date in the past for your basicDisbursement request which allows you to process unreferenced refunds.
More details
The payoutInstrument.cardHolderName field is no longer mandatory in v2 and v3 Payout requests.
More details
You can now request a Payout for the payoutInstrument card/networkToken+applepay.
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.
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."
}