Make a payment
Software providers Kaiwhakarato Pūmanawa Rorohiko

Investment income reporting through gateway services

Investment income reporting through gateway services lets organisations securely file investment income information to us through defined service operations. Use this service to file investment income information or amend a previously filed return.

Investment income reporting through the gateway services will be available for the following withholding tax product types:

  • Approved issuer levy (AIL)
  • Dividend withholding tax (DWT)
  • Interest pay as you earn (IPS)
  • Non-resident withholding tax (NRT)
  • Resident withholding tax (RWT)
  • Portfolio investment entities (PIE) attributed income - available later in 2019.

Information about investment income reporting

Find out more about the legislative changes for investment income reporting – including the information required the change to the frequency of reporting and when this comes into effect.

Find out how to opt-in to investment income reporting as an existing payer or new payer of withholding taxes
PDF | 537KB | 8 pages

Gateway services capability for investment income reporting

The gateway service used for investment income reporting is the Return service. It provides the following capabilities through defined service operations:

Service operation Description
File Enables payers to submit investment income information for a specific
reporting period and if required submit amendments to previously filed investment income information.
Pre-pop This operation is not applicable for investment income reporting
Retrieve Status Provides the processing status of previously filed investment investment income information for a specific reporting period.
Retrieve Return Provides a copy of previously filed investment income information for a specific reporting period.
Retrieve Return
Obligation
This operation is not applicable for investment income reporting.
Retrieve list This operation is not applicable for investment income reporting.

Back to top

Investment income reporting software developer kits (SDKs)

Access the investment income reporting software developer kits (SDKs) to help your build

Currently available for each withholding tax type Download the relevant SDKs
  • the schema (xsd) and supporting wsdl for the return service
  • sample messages for each service operation - requests and responses
  • Mock environment information including test scenarios, mind map and test data
  • Test environment information including test scenarios and mind map
  • the investment income information return service build pack that includes
    • data definitions of each operation
    • response status code definitions
Identity and access services
  • How to Integrate with OAuth
  • Sample curl commands - for testing the OAuth flow
  • Message Samples - OAuth requests and responses
  • Identity and access services build pack for details on
    • the token auth implementation using OAuth 2.0
    • desktop (native) application token auth

Supporting information

SOAP API architecture of gateway services

Learn about our soap API architecture that we offer through gateway services and how we authorise identity and access to our application types

Learn how to manage myIR logins for authorised representatives of an organisation so that access tokens can be generated for gateway services

Back to top

Investment income reporting business use cases

The following use cases are examples of sequences of the gateway service operations that can be used to achieve a specific business outcome when providing investment income information.

Number Use cases File Retrieve
Status
Retrieve
Return
1
File a single IIR return for a month period and subsequently optionally retrieve return status.
1
2*
 
2
File multiple IIR returns for a month period and subsequently optionally retrieve return status.
1
2*
 
3
Amend one or more line items in an IIR return as a single filer.
1
 
 
4
Amend one or more line items in an IIR return as a multi-filer.
1
 
 
5
Replace all data in an IIR return (Reverse Replace) - file an amended single IIR return the same period for all transactions.
1
 
 
6
Intermediary files an IIR return on behalf of a payer for a specific period and optionally retrieve return status.
1
2*
 
7
Retrieve IIR return as a single filer for the specific period.
 
 
1
8
Retrieve IIR return as a multi-filer for a specific period.
 
1*
2

Note: * indicates optional process steps.

Download detailed use cases and process flows for an investment income reporting tax type:

 

Back to top