Menu

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 ourAPI Principlesto ensure a resilient integration.

Versioning log

Breaking Changes

Version 3 introduces updates to the merchant response.

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

Before:

Copied!
{
    "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:

Copied!
{
    "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
        }]
    }
}

Breaking changes

Version 2 introduces 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 anerror

  • narrativenow has two lines in the JSON block:

Before:

Copied!
"narrative": "abc"

After:

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

Note: You can find documentation for all versionshere.

Change log (Non-breaking changes)

You can now provide billingAddress for bothbasicDisbursementandfastAccessrequests for Payouts v2 and v3. These fields improve success rates when provided for basicDisbursement requests. You can provide the billingAddress fields for fasAccess requests. This is useful when fastAccess isn't available and the Payout defaults to a basicDisbursement.

The cardExpiry can now be a date in the past for yourbasicDisbursement requestwhich allows you to process unreferenced refunds.

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

You can now request aPayoutfor the payoutInstrument card/networkToken+applepay.

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

Before:

Copied!
{
    "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:

Copied!
{
    "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
    }]
}

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

Before:

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

After:

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

The following characters are now allowed fornarrative:

  • abcdefghijklmnopqrstuvwxyz
  • spaces