Release Notes v18.19.1.481-rc

Friday, November 2, 2018 9:50 AM

Warning

This release contains a breaking change.

Story

  • [PRIO-419] - Remove legacy NI bands. The 2015 tax year bands should be retired.

Bug

  • [PRIO-427] - Spelling mistake in pro-rata enum

Breaking Change

Version 18.19.1.481 includes some changes to the schema which may break your implementation. Read the following to discover what has changed and if your implementation will be affected.

The Schedule

We plan to move API version 18.19.1.481 from pre-release to release on the following schedule.

After "Release", version 18.19.1.481 will be the default API target version. This means that if you do not set any "Api-Version" header value or set it to default, version 18.19.1.481 will be targeted.

TEST

Pre-Release: November 2nd, 2018

Release: November 12th, 2018

PRODUCTION

Release: November 19th, 2018

The Reason

National Insurance Model Simplification

To simplify the national insurance models [within the API], we have removed support for tax year 2015-16. During the 2015-16 tax year, it was possible to opt-out of state pension contributions. This process was handled using additional NI category letters and NI refunds. To support this behaviour the PayRun.io API NI pay line object and NI year to date pay instruction held additional properties.

From customer feedback we know that this made the objects unnecessarily complex and confusing to work with. So, we have decided it is now time withdraw support for tax 2015-16. In addition to the removal of the legacy properties, we have also renamed several bands to align them with the HMRC terminology.

Spelling Mistake

This release also contains a spelling correction. Pro-rata method DaysPerCalenderMonth has been renamed to DaysPerCalendarMonth.

The Impact

These updates result in a breaking schema change and you may need to amend your implementation.

You will be affected by this change if you have mapped any of the following object properties. Pay Line Ni or NI YTD Pay Instruction

  • STtoUEL
  • UAPtoUEL
  • UELtoUST
  • UELtoAUST
  • AboveUST
  • AboveAUST
  • RebateEE
  • RebateER

Pro-Rata Method

  • DaysPerCalenderMonth

Pre-Release Testing

A pre-release version of these changes has been made available in the PayRun.io test environment. This version is hosted side-by-side and can be accessed using the "Api-Version" HTTP header.

Using the "Api-Version" header, you can test the new release without breaking your existing implementation.

curl -X GET \
'https://api.test.payrun.io/Employer/ER001/Employee/EE001/PayLine/PLNI001 ' \
-H 'Accept: application/json' \
-H 'Api-Version: 18.19.1.481' \    << Note: additional header
-H 'Authorization: {OAuthHeader}' \
-H 'Cache-Control: no-cache' \
-H 'Content-type: application/json'

API Explorer

The Api-Header setting can be overridden in the Swagger API Explorer as illustrated below.

alt text

C# SDK

The C# SDK has also been updated to allow the injection of the API header.

Requires pre-release NuGet packages - version 18.19.1.481-rc.

class Program
{
    static void Main(string[] args)
    {
        var signatureGenerator = new OAuth1.OAuthSignatureGenerator();

        var apiHelper = new RestApiHelper(
            signatureGenerator,
            "CONSUMERKEY",
            "CONSUMERSECRET",
            "https://api.test.payrun.io/",
            "application/Json",
            "application/json");

        apiHelper.ApiVersionHeader = "18.19.1.481";

        var payLineNi = 
            apiHelper.Get<PayLineNi>(
                "/Employer/ER001/Employee/EE001/PayLine/PLNI001");
    }
}