Appearance
iPayroll integration overview
See API integration authentication and planning for the cross-integration view of how this token is obtained and whether advance planning is needed.
note
iPayroll does not accept non-NZ addresses
note
PICMI currently only supports one iPayroll integration for a single organisation. Contact us if you need to set up multiple.
Integration configuration
| Configuration | Description | Values |
|---|---|---|
| Token | Token provided for authentication | Retrieve the API key by application user |
| Employer Subsidy Contribution Tax Rate | Employer subsidy contribution tax (ESCT) | 10.5%, 17.5%, 30%, 33%, 39% |
| Employer Subsidy Rate | Employer subsidy | 0, 3.0, 3.5 (see here from more) |
| Payment Method | Payment method | Bank, Cheque, Cash |
| Payment Frequency | Payment frequency | Weekly, Fortnightly, Monthly |
| Cost Centre | Cost Center | Populated from iPayroll for your organisation |
| User Defined Group | User Defined groups | Populated from iPayroll for your organisation |
| Temporary Rate Reduction source | Source for the KiwiSaver temporary rate reduction end date | Job end date, Fixed date |
| Temporary Rate Reduction end date | Date on which the KiwiSaver temporary rate reduction ends | Date; required when the source is Fixed date |
PICMI-iPayroll integration fields
| Field Name | Description | Validation/Constraint/Default Value | Source |
|---|---|---|---|
| Id | Unique identifier for the record. | Integration Configuration | |
| First names | Given name(s) of the individual. | Personal Information | |
| Surname | Family name of the individual. | Personal Information | |
| Email address of the individual. | Personal Information | ||
| Phone | Phone number of the individual. | Personal Information | |
| Birthdate | Date of birth of the individual. | Personal Information | |
| Gender | Gender of the individual. | Personal Information | |
| Street address | The street address of the individual. | AddressPostal > StreetAddress | Personal Information |
| Locality | Locality of the address. | AddressPostal > Locality | Personal Information |
| City | City of the address. | AddressPostal > Region | Personal Information |
| Postcode | Postal code of the address. | AddressPostal > PostalCode | Personal Information |
| Country | Country of the address. | AddressPostal > CountryName | Personal Information |
| Address not supplied | Indicates if the address is not provided. | AddressPostal > NotSupplied | Personal Information |
| Bank account number | The individual's bank account number. | Questions | |
| Payment frequency | Frequency of payment (e.g., weekly, monthly). | Integration Configuration | |
| Payment method | Method of payment (e.g., direct deposit, cheque). | Integration Configuration | |
| KiwiSaver status | Current status of the individual's KiwiSaver membership. | Changeable on KiwiSaverStatus factors | Questions |
| KiwiSaver rate | Contribution rate for the KiwiSaver scheme. | Changeable on KiwiSaverStatus factors | Questions |
| Employer subsidy contribution tax rate (ESCT) | Tax rate for employer contributions to KiwiSaver. | Integration Configuration | |
| KiwiSaver age range | Age range applicable for KiwiSaver contributions. | Questions | |
| KiwiSaver casual auto enroll exempt | Indicates if the individual is exempt from automatic enrollment. | Changeable on KiwiSaverStatus factors | Questions |
| KiwiSaver opt-out date | Date the individual opted out of KiwiSaver contributions. | Changeable on KiwiSaverStatus factors | Questions |
| Employer subsidy | Amount of employer subsidy for KiwiSaver contributions. | Changeable on KiwiSaverStatus factors (auto populated) | Integration Configuration |
| Tax number (Inland Revenue Department (IRD) number) | Unique tax number for the individual. | Changeable on KiwiSaverStatus factors | Questions |
| Tax code | Tax code assigned to the individual for tax purposes. | Questions | |
| Start date | Start date of employment or contract. | Job | |
| Job title | Title of the individual’s position. | Job | |
| Pay rate | Rate of pay for the individual. | Job | |
| Temporary Rate Reduction end date | Date on which the KiwiSaver temporary rate reduction will end. | String in the iPayroll payload; dd/mm/yyyy preferred | Integration mapping or Integration Configuration |
Temporary Rate Reduction
Temporary Rate Reduction is an iPayroll-specific KiwiSaver status. When an employee has this status, PICMI must resolve the date on which the temporary rate reduction will end before sending the employee to iPayroll.
The iPayroll integration configuration exposes these fields:
| API field | Description | Values |
|---|---|---|
rateReductionEndDateSource | Selects how PICMI resolves the end date when no integration mapping is present. | job-end-date or fixed-date |
rateReductionEndDate | The configured end date used when rateReductionEndDateSource is fixed-date. | Date; required for fixed-date |
Integration mapping precedence
An integration mapping for rateReductionEndDate takes precedence over the iPayroll configuration fallback. PICMI resolves the end date in this order:
- Use an integration mapping for
rateReductionEndDatewhen one exists. - If no mapping exists, use the iPayroll configuration:
job-end-date: resolve the date from the job details' end date.fixed-date: use the configuredrateReductionEndDate.
- If no date can be resolved, validation fails before the outbound request.
Authorisation
How PICMI works with iPayroll
PICMI integrates with iPayroll via a separate user in your organisation that has the access role API User.
Retrieving a token
iPayroll uses an oAuth process to issue a token which requires you to have a separate user with the API user access that you agree to issue a token. This user is not your standard payroll user.
Note: you can only have one integration token activated on a single user for PICMI
note
if you are currently signed in with your payroll user, log out first so that you can log in with your API user.
- Use the URL provided by PICMI—if you are not logged
- Log in with your credentials that access to setting up an API
- Click Authorize
- Provide the token back to PICMI to be added to your integration
note
Updating a token in PICMI is currently not self-service and requires help from PICMI