Transaction Data Services (TDS) API

The TDS is a suite of business services that provides access to IR customers transaction data for consumption by software packages. In turn these packages present that data to their users. Financial transaction data includes amounts assessed and associated credits or debits. There is no data sent associated with the details of how an assessment has been calculated

Environment information

• Mock environment information - emulated service, scenarios mindmap and test data
• Test URL endpoints
• Production URL endpoints

About the Emulated Transaction Data Service API

This is an emulated service which emulates the TDS Gateway Service APIs. It provides static responses for a subset of scenarios invoked on each API.

Please note that not all requests and responses are emulated.

TDS API Build Pack

• Build pack - TDS API

TDS Business use cases

• Download and view

YAML

• TDS API YAML
• View YAML is a Swagger Editor

Reconciliation (Batch) Model

• Summary Status
• Summary
• Transactions/Batch

Realtime Model

• Financials
• Transactions/Realtime

Mock environment information

The hosted service is available at: https://tds-api.test.services.ird.govt.nz (IP Address whitlisting is required)

Mind Map

The mind map for the emulated service View larger image

Mock environment authentication

• Consumers of this mock service must be authenticated for the Realtime Model.
• Access delegation/restriction is not emulated, and any authenticated user has access to the test data.
  • OAuth
    • OAuth token issued by the mock OAuth service. Any valid token issued by the mock OAuth service can be used to access this service.
    • Please consult the mock OAuth service documentation for further details about the authentication process.
    • The OAuth token should be provided in the 'Authorization' request header as follows:

    Authorization: Bearer {OAuthAccessToken}
    

Test Data

Summary - Retrieve account summary

clientListId	linked account	filing periods
139702328	INC	2019-03-31, 2021-03-31
139723834	INC	2021-03-31

customerId	linked account	filing periods
139476387	FBT	2021-12-31, 2022-03-31
	GST	2021-12-31, 2022-03-31
	INC	2019-03-31, 2021-03-31
139723848	INC	2021-03-31
139724348	INC	2020-03-31, 2021-03-31

accountId	filing periods
139476387FBT005	2021-12-31, 2022-03-31
139476387GST004	2021-12-31, 2022-03-31
139476387INC002	2019-03-31, 2021-03-31
139723848INC002	2021-03-31
139724348INC002	2020-03-31, 2021-03-31

TransactionsBatch / TransactionsRealtime - Retrieve transactions

accountId	linked account	filing periods
139476387INC002	INC	2019-03-31, 2021-03-31

Financials - Retrieve financials

customerId	account	filing periods
139476387	FBT	2021-12-31, 2022-03-31
	GST	2021-12-31, 2022-03-31
	INC	2019-03-31, 2021-03-31

Example JSON requests and responses

/Summary

• 01-accountId_request

• 01-accountId_response

• 02-accountId-and-filingPeriodFrom_request

• 02-accountId-and-filingPeriodFrom_response

• 03-accountId-and-filingPeriodTo_request

• 03-accountId-and-filingPeriodTo_response

• 16-accountId-with-pendingPayment_request

• 16-accountId-with-pendingPayment_response

• 04-clientListId_request

• 04-clientListId_response

• 05-clientListId-accountType_request

• 05-clientListId-accountType_response

• 06-clientListId-and-filingPeriodFrom_request

• 06-clientListId-and-filingPeriodFrom_response

• 07-clientListId-and-filingPeriodTo_request

• 07-clientListId-and-filingPeriodTo_response

• 17-clientListId-with-pendingPayment_request

• 17-clientListId-with-pendingPayment_response

• 08-customerId_request

• 08-customerId_response

• 09-customerId-and-accountType_request

• 09-customerId-and-accountType_response

• 10-customerId-and-filingPeriodFrom_request

• 10-customerId-and-filingPeriodFrom_response

• 11-customerId-and-filingPeriodTo_request

• 11-customerId-and-filingPeriodTo_response

• 18-customerId-with-pendingPayment_request

• 18-customerId-with-pendingPayment_response

• 12-TDS102-accountId-and-accountType_request

• 12-TDS102-accountId-and-accountType_response

• 13-TDS102-missing-required-field_request

• 13-TDS102-missing-required-field_response

• 14-TDS102-accountId-customerId-clientListId_request

• 14-TDS102-accountId-customerId-clientListId_response

• 15-TDS301-invalid-accountId_request

• 15-TDS301-invalid-accountId_response

/Transactions

• 01-accountId-and-filingPeriod_request

• 01-accountId-and-filingPeriod_response

• 02-TDS302-accountId-and-invalid-filingPeriod_request

• 02-TDS302-accountId-and-invalid-filingPeriod_response

/Financials

• 01-accountId_request

• 01-accountId_response

• 02-accountId-filingPeriodTo_request

• 02-accountId-filingPeriodTo_response

• 03-accountId-filingPeriodFrom_request

• 03-accountId-filingPeriodFrom_response

• 04-customerId_request.json

• 04-customerId_response

• 05-TDS102-customerId-and-filingPeriod_request

• 05-TDS102-customerId-and-filingPeriod_response

Mock Test Report Templates

• TDS API Realtime
• TDS API Reconciliation (Batch)

Digital Testing Environment information

• Slice Data URL Endpoint: https://test5.services.ird.govt.nz:4046/gateway/tds/

Test Report Templates

• TDS API Realtime - Test Report Template
• TDS API Reconciliation (Batch) - Test Report Template

Production Environment information:

• URL Endpoint: https://services.ird.govt.nz:4046/gateway/tds/

PLEASE NOTE: IR requires DSP’s to provide a separate mutual TLS certificate which will be used exclusively for the TDS API /Summary and /transaction/batch.

Supporting services

• Customer Services Suite
• Service - Intermediation
• Service - Software Intermediation
• Service - Identity and Access