The bank account API enables the creating and deleting of the refund bank account for an identified customer’s account. It is 1 of 7 APIs that, together, make up the customer services suite.
If you have any questions about the bank account API or using gateway services for the bank account API, email us at GatewayServices@ird.govt.nz
How the bank account API works
The bank account API requires the account API to be integrated.
The bank account API enables the refund bank account held at the customer account level to be added and deleted. It requires the account ID for the addition or deletion of a refund bank account. The account ID is available through a call to the account API.
Note that the add function is effectively an update function if a refund bank account already exists on the customer account. It replaces the existing refund bank account with the added refund bank account in this scenario.
The bank account API can only be used by:
- the customer the data is associated to
- a user with delegated access
- an intermediary who’s linked to the customer
- government agencies with a memorandum of understanding that allows them access to customer account level data.
The bank account API enables the above users to update Inland Revenue’s customer account data from their native systems, and to avoid the use of manually facilitated channels.
Software developer kit (SDK)
View and download the software developer kit (SDK) for the customer services suite to help you integrate:
- test scenarios
- test data
- sample request and response messages
- the Open API YAML file
- the build pack that provides the data definitions for the request and response messages.
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
Gateway service capability for the bank account API
The bank account API provides the following capabilities through defined API operations and API paths.
|API operation||API path||Description|
This operation either:
|DELETE||/bank||Deletes the refund bank account from the identified customer account.|
Bank account API business use cases
The following are examples of how to use the bank account API to achieve specific business outcomes. The sequence of operations, the order in which they should be called, is indicated in the column of each operation.
|Number||Use case||POST /bank||DELETE /bank||Dependencies|
|1||Add the refund bank account to an identified customer account.||1||Customer account ID has been obtained from the account API.|
|2||Update the refund bank account to an identified customer account.||1||Customer account ID has been obtained from the account API.|
|3||Remove the existing refund bank account from an identified customer account.||1||Customer account ID has been obtained from the account API.|