Introduction

The Payetools.io service provides a straightforward API for submitting RTI documents to HMRC.

Data Flow

sequenceDiagram Application->>+Service: Submit FPS/EPS/NVR Service->>+HMRC: Submit message HMRC->>-Service: Submitted Service->>-Application: Submission sent loop Service->>+HMRC: Poll HMRC->>-Service: Response end Service->>WebhookHandler: Submission acknowledged Application->>+Service: Message processed* Service->>+HMRC: Delete HMRC->>-Service: Delete response Service->>-Application: _

* This step is optional. Payetools.io can be configured to automatically delete messages once the webhook has been successfully delivered.

[example| propertyA: Int propertyB: string | methodA() methodB() | [subA]--[subB] [subA]-:>[sub C] ]

This is an example¹ of footnote usage.

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

~~strike through~~ example

_subscript example

^superscript example

inserted example

marked example

Header 1

Link back to header1

Header 2

Le Site

http://digitaltapestry.net

This is a "text"

This is a 'text'

This is a <>

This is a "text

This is a "text 'with" a another text'

This is a -- text

This is a --- text

This is a en ellipsis...

namespace Amido.VersionDashboard.Web.Domain {
    public interface IConfigProvider {
        string GetSetting(string appSetting);
    }
}

{
    "blah": 12
}

An example footnote.↩

Field Name	Field Type	Comment
`Credentials`	IRtiCredentials	Gets the RTI credentials used for the submission; this is typically the Government Gateway login username and password for the employer or its agent.
`TestSubmissionMode`	TestSubmissionMode	Gets the test transmission mode; indicates whether the message should be submitted to the test or live gateway, and in the case of the latter, whether the message should be treated as a production or test-in-live message. Defaults to TestSubmissionMode.None, i.e., live production submission.
`ResponseOptions`	IRtiSubmissionResponseOptions	Gets the options that specify responses to the submission should be handled.
`NotificationEmail`	string?	Gets the email to be used by HMRC to send notifications regarding this submission. Optional.

Field Name	Field Type	Comment
`NiNumber`	string	Gets or sets the employee's National Insurance number.
`Name`	ContactName	Gets or sets the employee's name details.
`Address`	Address	Gets or sets the employee's postal address.
`DateOfBirth`	DateTime	Gets or sets the employee's date of birth.
`Gender`	Gender	Gets or sets the employee's gender.
`PassportNumber`	string?	Gets or sets the employee's passport number. Optional.
`PartnerDetails`	EmployeePartner?	Gets or sets the employee's partner's details. Optional.

title: Help Center navigation:

section: Help Center
document: overview_doc label: Overview
document: data_sources_doc label: Data Sources
document: data_definitions_doc label: Data Definitions
document: faq_doc label: FAQ
document: release_notes_doc label: Release Notes

Administration

Database Migrations

The endpoint /admin/migratedatabase is used to migrate the database up or down. It takes the following parameters:

Parameter	Valid values	Comment
`direction`	`up` or `down`	Must be provided
`migrateDownTo`	Any valid migration identifier or `0`	Only used with `direction` = `down`. Optional.

Full Payment Submission

Getting Started

Here's an example of a Full Payment Submission (FPS) JSON payload:

{
  "header": {
    "credentials": {
      "password": "**************",
      "senderId": "ISV635"
    },
    "testSubmissionMode": "testGateway",
    "responseOptions": {
      "replyTo": "https://play.svix.com/in/e_MylLlDl3cGQrEwgpxlAP46HMdE4/",
      "includeEncodedSubmissionInResponse": false,
      "includeEncodedResponseInResponse": false
    },
    "hmrcNotificationEmail": "steve@blah.com"
  },
  "submission": {
    "employeeEntries": [
      {
        "employeeDetails": {
          "niNumber": "NA123511C",
          "name": {
            "title": "Mr",
            "forenames": [
              "Gordon",
              "Humphrey"
            ],
            "surname": "Jones"
          },
          "address": {
            "addressLine1": "1 Longriding Street",
            "addressLine2": "Little Pomham",
            "addressLine3": "Wiltington",
            "postcode": "EX1 7QP"
          },
          "dateOfBirth": "1970-03-20T00:00:00",
          "gender": "male"
        },
        "employmentDetails": [
          {
            "ytdFigures": {
              "taxablePayYtd": 0,
              "totalTaxYtd": 0,
              "studentLoansYtd": 0,
              "postgradLoansYtd": 0,
              "payrolledBenefitsYtd": 0,
              "employeePensionContributionsYtd": 0,
              "employeePensionContributionsNotPaidYtd": 0
            },
            "paymentDetails": {
              "payFrequency": "monthly",
              "paymentDate": "2024-06-30T00:00:00",
              "monthNumber": 2,
              "numberOfPeriodsCovered": 1,
              "normalHoursWorked": "a",
              "taxCode": "1257L",
              "taxablePay": 0,
              "deductionsFromNetPay": 0,
              "payAfterStatutoryDeductions": 0,
              "payrolledBenefits": 0,
              "class1ANICsYtd": 0,
              "employeePensionContributionsUnderNPA": 0,
              "studentLoanPayments": 0,
              "studentLoanType": "plan4",
              "taxDeductedOrRefunded": 0
            },
            "niDataEntries": [
              {
                "niCategory": "a",
                "grossEarningsForNICsInPeriod": 0,
                "grossEarningsForNICsYtd": 0,
                "atLELYtd": 0,
                "leLtoPTYtd": 0,
                "pTtoUELYtd": 0,
                "totalEmployerNICsInPeriod": 0,
                "totalEmployerNICsYtd": 0,
                "employeeNICsInPeriod": 0,
                "employeeNICsYtd": 0
              }
            ]
          }
        ]
      },
      {
        "employeeDetails": {
          "niNumber": "SE194511C",
          "name": {
            "title": "Ms",
            "forenames": [
              "Sally",
              "Jane"
            ],
            "surname": "Tomlinson"
          },
          "address": {
            "addressLine1": "152 Wisley Drive",
            "addressLine2": "Bonningham",
            "postcode": "UD7 9DF"
          },
          "dateOfBirth": "1980-07-03T00:00:00",
          "gender": "female"
        },
        "employmentDetails": [
          {
            "ytdFigures": {
              "taxablePayYtd": 0,
              "totalTaxYtd": 0,
              "studentLoansYtd": 0,
              "postgradLoansYtd": 0,
              "payrolledBenefitsYtd": 0,
              "employeePensionContributionsYtd": 0,
              "employeePensionContributionsNotPaidYtd": 0
            },
            "paymentDetails": {
              "payFrequency": "monthly",
              "paymentDate": "2024-06-30T00:00:00",
              "monthNumber": 2,
              "numberOfPeriodsCovered": 1,
              "normalHoursWorked": "a",
              "taxCode": "1263L",
              "taxablePay": 0,
              "deductionsFromNetPay": 0,
              "payAfterStatutoryDeductions": 0,
              "payrolledBenefits": 0,
              "class1ANICsYtd": 0,
              "employeePensionContributionsUnderNPA": 0,
              "studentLoanPayments": 0,
              "studentLoanType": "plan4",
              "taxDeductedOrRefunded": 0
            },
            "niDataEntries": [
              {
                "niCategory": "a",
                "grossEarningsForNICsInPeriod": 0,
                "grossEarningsForNICsYtd": 0,
                "atLELYtd": 0,
                "leLtoPTYtd": 0,
                "pTtoUELYtd": 0,
                "totalEmployerNICsInPeriod": 0,
                "totalEmployerNICsYtd": 0,
                "employeeNICsInPeriod": 0,
                "employeeNICsYtd": 0
              }
            ]
          }
        ]
      }
    ],
    "periodEnd": "2024-07-05T00:00:00",
    "iRheaderContact": {
      "contactType": "principal",
      "name": {
        "title": "Mr",
        "forenames": [
          "Anthony",
          "George"
        ],
        "surname": "Tomlinson"
      }
    },
    "sender": "company",
    "hmrcPayeReference": "635/A635",
    "accountsOfficeReference": "120PF61837501"
  }
}