SS Contributions examples

{
  "$schema": "https://spcm.gov.gg/schemas/0.3/message.schema.json",
  "spcmMessageVersion": "0.3",
  "effective": "2023-10-05T16:33:05Z",
  "senderEmail": "joseph@acme.gg",
  "senderName": "Joseph Administrator",
  "softwareAgent": "SPCMTasks",
  "type": "Revenue_EmployerReturn",
  "purposes": [
    "SSContributions"
  ],
  "test": false,
  "coverage": [
    {
      "frequency": "Monthly",
      "year": 2023,
      "period": 7
    },
    {
      "frequency": "Monthly",
      "year": 2023,
      "period": 8
    },
    {
      "frequency": "Monthly",
      "year": 2023,
      "period": 9
    }
  ],
  "employers": [
    {
      "id": "SPCM-12345-SocialSecurity",
      "name": "Acme Widgets",
      "socialSecurityNo": "123456",
      "employees": [
        {
          "id": "1",
          "socialSecurityNo": "GY233445",
          "firstName": "Joan",
          "lastName": "Bloggs",
          "dateOfBirth": "1980-01-01",
          "ssCard": "Blue",
          "employmentStartDate": null,
          "employmentEndDate": "2023-08-31",
          "leftIsland": false,
          "purposes": [
            "SSContributions"
          ],
          "pay": [
            {
              "frequency": "Monthly",
              "year": 2023,
              "period": 7,
              "earnings": 4444.44,
              "employeeSSContributions": 444.44,
              "employerSSContributions": 333.33
            },
            {
              "frequency": "Monthly",
              "year": 2023,
              "period": 8,
              "earnings": 4444.44,
              "employeeSSContributions": 444.44,
              "employerSSContributions": 333.33
            }
          ]
        }
      ]
    }
  ]
}

Please note this documentation assumes you are familiar with the concepts explained in the example files for Secondary Pensions compliance.

"type": "Revenue_EmployerReturn"

"purposes": [ "SSContributions" ]

These headers indicate that this an employer's Social Security Contributions return.

"coverage"

The coverage array here indicates that the report covers the monthly payroll for 2023 Q3. The array is a list of periods, each identified by its year, frequency ("Monthly" or "Weekly"), and period (which ranges from 1-12 for months, and 1-53 for weeks).

"employers"

This employers array contains one employer. It is expected that almost all returns will only contain one employer, but the format allows for multiple employers in the event that a single sender administers a group of related employers together.

"id"

minLength: 1; maxLength: 200

This is an identifier for the employer which is generated by the sender. It is defined as a string, and it does not matter what identifier you use, but you should use the same Id to refer to the same employer when sending successive messages.

The employer Id can only identify an employer within the scope of an API key. This means two messages received by SPCM will only be treated as referring to the same employer if both were sent with the same API key, as well as having the same employer Id.

"name"

minLength: 1; maxLength: 160

The name of the employer.

"socialSecurityNo"

pattern: \d{6}

The six-digit social security reference number of the employer.

"employees"

This array must list all the employees for whom contributions data is reportable for any period covered by this return.

"id"

minLength: 1, maxLength: 200

This is an identifier for the employee which is generated by the sender. It can be any string, but it should be immutable. It identifies the employee within the scope of the employer, so if you are reporting for two or more employers using the same API key, then it is acceptable to have the same Id for two different people where they are employed by different employers.

"socialSecurityNo"

pattern: [A-Z]{2}\d{6}

The employee's Guernsey social security number, which must be two upper case letters followed by six digits.

"firstName"

minLength: 1; maxLength: 50

The employee's first name. If only initials are known then provide these.

"lastName"

minLength: 1; maxLength: 50

The employee's last name.

"dateOfBirth"

The employee's date of birth.

"ssCard"

"Blue", "Orange" or null

The type of Social Security card held by the employee.

"employmentStartDate"

The date the employee started working for this employer in ISO 8601 (yyyy-mm-dd) format. If the employee started working for the employer during the periods covered by this report, this field should be populated. If the employee started their current term of employment before the beginning of the periods being reported, the field may be populated with the date they started, or it may be null.

"employmentEndDate"

The date the employee ceased working for this employer in ISO 8601 (yyyy-mm-dd) format. If the employee is still employed, this must be null.

"leftIsland"

If the employee has left the island after ceasing their employment with this employer, this should be true, otherwise it should be false.

"purposes"

In this example, this array contains the single value "SSContributions", which indicates that this employee falls within the scope of Contributions reporting.

Normally, the purposes listed for a each employee will be the same as the purposes in the message header. However, there may be situations where certain employees are not reportable for one or more of those purposes. This array is provided so that, in such cases, you can still provide a single combined return, rather than having to split a return into a separate file for each purpose.

"pay"

The pay array contains an object for every period covered by the return in which this employee was paid.

The year, frequency and period indicate the period covered by the object.

The period must be one of those in the "coverage" array in the return header, and each period included must only appear once.

If any period in the coverage array is missing from the pay array (such as period 9, September, in the example above), this means the employee was not paid in that period. This is equivalent to reporting a pay object with zero for all values.

All currency amounts are in pounds sterling.

"earnings"

minimum: 0; exclusiveMaximum: 100000000

The gross earnings for the employee for this period

"employerSSContributions"

minimum: 0; exclusiveMaximum: 100000000

The employer's contributions for the period

"employeeSSContributions"

integer; minimum: 0; exclusiveMaximum: 100000000

The employee's contributions for the period'