National Insurance and State Pension

This microservice retrieves data from a HoD system called NPS, for calculating State Pension Age and Amount.

Requirements

This service is written in Scala and Play, so needs at least a JRE to run.

API

State Pension Summary

Fetches the SPResponseModel object for the frontend service.

URL

nisp/:nino/spsummary
Method:

GET
URL Params

Required:

nino=[nino]

The NINO given must be a valid NINO.
Success Response:
- Code: 200
  Content:

{
    "spSummary":{
        "nino":"QQ000000A",
        "lastProcessedDate":"05/04/2014",
        "statePensionAmount":{
            "week":154.94,
            "month":673.71,
            "year":8084.55
        },
        "statePensionAge":{
            "age":65,
            "date":"06/09/2019"
        },
        "contextMessage":"ScenarioOne",
        "finalRelevantYear":2018,
        "numberOfQualifyingYears":35,
        "numberOfGaps":10,
        "numberOfGapsPayable":4,
        "yearsToContributeUntilPensionAge":5,
        "hasPsod":false,
        "dateOfBirth":"09/03/1954",
        "forecastAmount":{
            "week":159.62,
            "month":694.06,
            "year":8328.74
        },
        "fullNewStatePensionAmount":151.25,
        "contractedOutFlag": false,
        "customerAge": 61,
        "copeAmount":{
            "week": 0.00,
            "month": 0.00,
            "year": 0.00 
        }
    }
}

Error Response:
- Code: 404 NOT FOUND Reason: NINO could not be found Content: json{}
Other Response:
- Code: 200 Reason: User is excluded from service Content:

{
    "spSummary":{
       ...
    }
    "spExclusions":{
        "exclusions":["Abroad", "MWRRE"]
    },
    "niExclusions":{
        "exclusions":["MWRRE"]
    }
}

** IF THE USER IS EXCLUDED THE PENSION AMOUNT INFORMATION IS INACCURATE AND SHOULD NOT BE PRESENTED **

National Insurance Record

Fetches the NIResponseModel object for the frontend service.

URL

nisp/:nino/nirecord
Method:

GET
URL Params

Required:

nino=[nino]

The NINO given must be a valid NINO
Success Response:
- Code: 200
  Content:

{
  "niRecord": {
    "taxYears": [
      {
        "taxYear": 1975,
        "qualifying": true,
        "classOneContributions": 70.67,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 26,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
      {
        "taxYear": 1976,
        "qualifying": true,
        "classOneContributions": 53.5,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 34,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
      {
        "taxYear": 1977,
        "qualifying": true,
        "classOneContributions": 82.13,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 28,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
      {
        "taxYear": 1978,
        "qualifying": true,
        "classOneContributions": 69.35,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 41,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
      {
        "taxYear": 1979,
        "qualifying": true,
        "classOneContributions": 24.9,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 42,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
      {
        "taxYear": 1980,
        "qualifying": true,
        "classOneContributions": 114.19,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 35,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
...
      {
        "taxYear": 2010,
        "qualifying": false,
        "classOneContributions": 0,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 4,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
      {
        "taxYear": 2011,
        "qualifying": false,
        "classOneContributions": 0,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 0,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      },
      {
        "taxYear": 2012,
        "qualifying": false,
        "classOneContributions": 0,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 12,
        "classThreePayable" : 638.00,
        "classThreePayableBy": "01/01/2022",
        "payable": true
      },
      {
        "taxYear": 2013,
        "qualifying": true,
        "classOneContributions": 2430.24,
        "classTwoCredits": 0,
        "classThreeCredits": 0,
        "otherCredits": 0,
        "classThreePayable" : null,
        "classThreePayableBy": null,
        "payable": false
      }
    ]
  },
  "niSummary": {
    "noOfQualifyingYears": 35,
    "noOfNonQualifyingYears": 10,
    "yearsToContributeUntilPensionAge": 5,
    "spaYear": 2019,
    "earningsIncludedUpTo": "05\/04\/2014",
    "unavailableYear": 2014,
    "pre75QualifyingYears": 5,
    "numberOfPayableGaps": 4,
    "numberOfNonPayableGaps": 6,
    "canImproveWithGaps": false
  }
}

Error Response:
- Code: 404 NOT FOUND Reason: NINO could not be found Content: json{}
Other Response:
- Code: 200 Reason: User is excluded from service Content:

{
    "spExclusions":{
        "spExclusions":["Abroad"]
    }
}

Configuration

This service requires configuration for other services, for example NPS requires:

Key	Description
`microservice.services.nps-hod.protocol`	The protocol of the NPS service
`microservice.services.nps-hod.host`	The host of the NPS service
`microservice.services.nps-hod.port`	The port of the NPS service

Acronyms

In the context of this application we use the following acronyms and define their meanings. Provided you will also find a web link to discover more about the systems and technology.

API: Application Programming Interface
HoD: Head of Duty
JRE: Java Runtime Environment
JSON: JavaScript Object Notation
NI: National Insurance
NINO: National Insurance Number
NPS: National Insurance and Pay As You Earn Service
URL: Uniform Resource Locator

License

This code is open source software licensed under the Apache 2.0 License.

andrewgee/nisp