We're prioritising digital service providers whose design solutions make it easy for end users to meet their tax obligations and receive their social policy entitlements. We'll contact you to discuss how your software achieves this before we start any gateway services integration.
The prescribed investor rate (PIR) calculator service provides a suggested prescribed investor rate for an individual customer.
If you have any questions about the PIR calculator service or using gateway services for the PIR calculator service, email GatewayServices@ird.govt.nz
How the PIR calculator service works
Income from PIE (portfolio investment entity) investments is taxed at a rate called the prescribed investor rate or PIR.
Because PIRs are chosen when a customer opens an account but the tax is squared up at a later date, the PIR may be out of date. The PIR calculator service can assist in this scenario by providing a suggested prescribed investor rate for an individual customer.
The customer in consultation with their PIE provider is responsible for using the correct prescribed investor rate.
Software developer kit (SDK)
View and download the PIR calculator service software developer kit to help you integrate:
- sample request and response messages
- the Open API YAML file
- the build pack that provides the data definitions for the request and response messages
- test scenarios
- test data.
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
Gateway service capability for the PIR calculator service
The gateway service is the PIR calculator service API. It provides the following capabilities through a defined service operation:
|Post||Retrieves a customer's suggested prescribed investor rate from Inland Revenue.|
The identity attributes that need to be supplied are:
- the individual investor's IRD number
- the PIE's IRD number
- the investor’s name, date of birth and address (only for non-KiwiSaver PIEs)
PIR calculator service business use cases
The following are examples of sequences of the gateway PIR calculator service operations that could be used to achieve a specific business outcome. The numbers for each use case are the order in which these operations should be called when using this services.
|1||View a customer's prescribed investor rate||1|