PayHero integration overview

PayHero: Integration configuration

Configuration	Description	Values
API key	Partner API key used to authenticate requests to PayHero	Text (required)
Employer Subsidy Contribution Tax Rate	Tax rate deducted from Superannuation Employer Contribution, expressed as a percentage	PayHero/NZ tax rates lookup
Default pay cycle	PayHero pay cycle applied on employee creation	PayHero pay cycles
Email payslips	Send payslips via email	Send email payslips if there is a provided email address; Never send email payslips
Default employee status on creation	PayHero employee status applied on employee creation	PayHero employee statuses
Add holiday pay as you go	Whether to apply Holiday Pay As You Go	Yes, apply holiday pay as you go; No, do not apply holiday pay as you go
Employee label	Static label applied to all employees created via PICMI	Label is added to the employee
Employee label color	Hex color code for the static label (defaults to PICMI’s spring green: #25ce81)	Hex color
Add role-based label	Automatically apply a label based on the employee’s role in PICMI	Yes, apply role-based labels; No, do not apply role-based labels (uses Job Title)
Role label color	Hex color code for automatically applied role-based labels (defaults to PICMI’s spring green: #25ce81)	Hex color

PICMI-PayHero integration fields

Field Name	Description	Validation/Constraint/Default Value	Source
First name	Given name of the individual.	Mandatory	Personal Information
Surname	Family name of the individual.	Mandatory	Personal Information
Preferred name	Preferred name used by the individual, typically the first and surname combined.	First + Surname, Mandatory	Personal Information
Email	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 identity of the individual.	Gender Diverse	Personal Information
Street address	Street address of the individual.	AddressPostal > StreetAddress	Personal Information
City	City where the individual resides.	AddressPostal > Region	Personal Information
Postcode	Postal code for the individual's address.	AddressPostal > PostalCode	Personal Information
Emergency contact name	Name of the individual's emergency contact.		Questions
Emergency contact phone	Phone number of the individual's emergency contact.		Questions
Bank account number	Bank account number of the individual (stripped of dashes).		Questions
Tax number	Individual's tax number (IRD number, stripped of dashes).	Mandatory	Questions
Tax code	Tax code applicable to the individual.	Mandatory	Questions
Start date	Start date of employment or contract.	Today + 1 day, Mandatory	Job
Job title	Title of the individual's position.		Job
KiwiSaver pre-existing member	Indicates if the individual is a pre-existing KiwiSaver member.	Changable on KiwiSaverStatus contribution rate mapping	Questions
KiwiSaver rate	Contribution rate for KiwiSaver.	Changable on KiwiSaverStatus contribution rate mapping	Questions
KiwiSaver opt-out date	Date set when an individual opts out of KiwiSaver.	Changable on KiwiSaverStatus contribution rate mapping	Questions
Enrolment date	Date of enrolment in KiwiSaver.	Changable on KiwiSaverStatus contribution rate mapping	Questions
Employer subsidy contribution tax rate (esct)	Tax rate for employer subsidy contributions.		Integration Configuration
Pay rate	Rate of pay for the individual.		Job
Salary flag	Indicator for salary employment type; must be set to avoid API errors.	FALSE, Mandatory	Integration Configuration
Contractor flag	Indicator for contractor employment type; must be set to avoid API errors.	FALSE, Mandatory	Integration Configuration
Active flag	Status indicator for employment; defaults to TRUE if active.	TRUE	Integration Configuration
Email pay slips	Preference for receiving payslips via email.	Email payslip to provided email address	Integration Configuration
Payment cycle	Cycle for payment processing.	API + No Pay Cycle, No PayCycle	Integration Configuration

API Key Management for PayHero Integration

To create an employee in PayHero requires a PICMI partner API access key.

note

PICMI supports only one API access key to be used across all PayHero integrations on an organisation. Please contact PICMI support if you require more than one API access key for your organisation.

Request a PICMI partner API access key

The key can only be received by email from an email request to PayHero Support. Click this link to open an email template in your mail client.

To: support@payhero.co.nz
Subject: PICMI partner API access key
Body Please provide me with the PICMI partner API access key to be used for my organisation

Who is doing what

Actor	Description
Shared Customer	Business using both PICMI and PayHero.
PICMI	Integration partner facilitating the connection between shared customer and PayHero.
PayHero Team	Owner of the API infrastructure, responsible for generating partner-specific API keys.

note

The customer can have their own private API keys to act for themselves and provide partner keys to third-party like PICMI

Responsibilities

Actor	Responsibilities
Shared Customer	Notify PayHero that they are using PICMI as their integration partner and request a PICMI-specific API key from the PayHero team to ensure compatibility with the integration.
PICMI	Use the PICMI-specific API key for each request to ensure both the customer and PayHero know the request is from PICMI.
PayHero Team	Generate PICMI-specific API keys upon request for shared customers, ensuring they are added to the PICMI integration for verification.

note

The partner API key for PICMI is not viewable to the customer through the PayHero application but is provided via email

General troubleshooting

• General integration troubleshooting
• Integration FAQs

How long does it take for PayHero to respond with an API access key?

+

Where is the PICMI partner API access key in the application?

+

I have the error 'Invalid API key', what should I do?

+