Make a payment
Software providers Kaiwhakarato Pūmanawa Rorohiko

Operations and message structure

The structure of our operations produces efficient requests and responses. Common structure and fields are used across different schemas and tax types.

XSD schema structure

The XSD schema structure for gateway services are:

  • Common.xsd
  • ServiceCommon.xsd
  • SpecificProduct.xsd

All schemas for different services import a common.xsd which has some data types specific to Inland Revenue.

This common.xsd will be used in other gateway services outside of the /<namespace>/namespace and must be kept up-to-date.

To view the service operations, schemas and data definitions:

SOAP messages structure

All messages require a header containing the Action: parameter. The body must contain a structured XML payload.

Refer to the WSDL for the correct addresses. Refer to samples or the WSDL element wsdl:binding/soap12:operation/soapAction for the URL to use.

The online WSDLs for gateway services define an 'any' XML request and response structure, which then relies on a group of XSDs to define the data structure of those requests and responses.

Each request and response type will define a lower, 'wrapper' element. To simplify analysis and code generation, a development oriented version of the WSDL and XSDs is provided with the build pack that has the 'any' elements replaced with relevant types.

Schema (xsd) validations

When you send structured XML through gateway this will be checked against our published XSDs.

This is partially a late binding validation, performed after an authentication review. The message structure of these services is a simple request/response. 

The XML request will be checked for well-formed XML before the schema validation. Responses to these requests will be in XML format and defined by the same schemas as requests.

Any XML submissions in the body that do not meet the provided schemas will not be accepted. Incorrect namespaces will also fail validation against the published schemas.

Any malformed XML will instantly be rejected before any schema validation.

Example SOAP request structure

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"

xmlns:sft="https://services.ird.govt.nz/GWS/SoftwareIntermediation/"

xmlns:gcl="https://services.ird.govt.nz/GWS/SoftwareIntermediation/:types/RetrieveClientListRequest"

xmlns:a="http://www.w3.org/2005/08/addressing">

     <soap:Header>

 <a:Action>https://services.ird.govt.nz/GWS/SoftwareIntermediation/SoftwareIntermediation/Operation</a:Action> 

     </soap:Header>

     <soap:Body>

<sft:RetrieveClientList>

     <sft:RetrieveClientListRequestMsg>

         <rcl:RetrieveClientListRequestWrapper>

             <RetrieveClientListRequest xmlns:xsi…

                <…XML payload…>

             </RetrieveClientListRequest>

         </rcl:RetrieveClientListRequestWrapper>

     </sft:RetrieveClientListRequestMsg>

</sft:RetrieveClientList>

     </soap:Body>

</soap:Envelope>

Example SOAP response structure

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"  xmlns:a=http://www.w3.org/2005/08/addressing

xmlns:si=http://services.ird.govt.nz/GWS/SoftwareIntermediation/

xmlns:b=http://services.ird.govt.nz/GWS/SoftwareIntermediation/:types/RetrieveClientListResponse

xmlns:i=http://www.w3.org/2001/XMLSchema-instance

xmlns:cmn="urn:www.ird.govt.nz/GWS:types/Common.v1">

      <s:Header>

<a:Action s:mustUnderstand="1">

https://services.ird.govt.nz/GWS/SoftwareIntermediation/SoftwareIntermediation/RetrieveClientListResponse

</a:Action>

      </s:Header>

      <s:Body>

            <si:RetrieveClientListResponse >

 <si:RetrieveClientListResult>

        <b:RetrieveClientListResponseWrapper>

             <cmn:RetrieveClientListResponse>

                <cmn:statusMessage>

                    <cmn:statusCode>0</statusCode>

                    <cmn:errorMessage/>

                </cmn:statusMessage>

             </cmn:RetrieveClientListResponse>

                     </b:RetrieveClientListResponseWrapper>

               </si:RetrieveClientListResult>

           </si:RetrieveClientListResponse>

       </s:Body>

</s:Envelope>