Table of contents

CTC Traders API trader test guidance and support

General guidance

This reference page signposts software developers to essential information and materials. You’ll need this information when developing and testing your software to interact and work with our CTC Traders API and HMRC systems. We’ve included more detailed instructions further down this page.

General introduction to CTC

Essential reading

Essential developer materials

Detailed guidance

This section provides more detailed information and instructions to new software developers using our CTC Traders API. You’ll need this information when developing and testing your software to ensure it is compatible with our CTC Traders API and HMRC Systems.

We strongly advise you to start testing your software for compatibility purposes as soon as possible.

Push pull notifications

Note: if your endpoint is hosted by Amazon Web Services (AWS) then you must either use edge-optimised custom domain names or regional custom domain names.

When testing your software, you can be sent automatic notifications using the Push Pull Notifications API. This is where notifications of new messages from NCTS to you can be pushed to your software in near real time. To get these automatic messages, you must:

  • subscribe to the Push Pull Notifications service
  • subscribe to the CTC Traders API in the sandbox environment
  • configure the notification URL in the subscription configuration section of Developer Hub:

To subscribe to the Push Pull Notifications service, go to Developer Hub.

To find out more information about go to push pull notifications.

This sequence diagram visualises the push pull notification components and process whereby your service needs to return a 200 HTTP status as part of the automated notification process. Use the Push Pull Notifications service to get notifications (pull) and to receive notifications (push) automatically.

Test your scenarios

  • Our API lets software developers and test engineers submit departure and arrival movement notifications into our sandbox testing environment.
  • You can test your software by using our sandbox to ensure that its connectivity works properly with HMRC systems.

Trader Test simulates both the automated responses and also the real life experience where NCTS support staff do the tasks of Border Force personnel. So during your testing when you require a manual response, they will perform the live manual steps of the process. This simulates and tests a full real-life journey from start to finish for you.

You must

  1. Test common scenarios using our CTC Traders API Test Pack. This gives you all the reference data you need to do our tests plus any of your own tailored tests.
  2. Check against our XSDs for schema validation. You can download a zip file with all the CTC Traders API XSDs.
  3. Cross reference with TIS Appendix B Technical Message Structures to check which data fields are optional and mandatory.
  4. When you need a manual response, email us to request this. You can find more information about this in the NCTS Access and Channels document.

How to get set up for testing

  1. First register for a developer account. You can do this by following the instructions on the Using the Developer Hub page.
  2. Sign back in to the HMRC Developer Hub
  3. Create an application by going to the Create Test User API
  4. Then create another application by going to the Common Transit Convention Traders API
  5. Create a user ID and password for either an individual or an organisation
  6. Subscribe to our Common Transit Convention Traders API on the developer hub under the section called Your Specific Applications
  7. Create a Client ID and Client Secret
  8. Use the Create Test User API to get a user ID, password, EORI enrolment and other test details. Ensure you include the CTC Trader EORI enrolment by including the following request body in the call to the Create Test User API:

{
  "serviceNames": [
    "common-transit-convention-traders"
  ]
}

How to test using sample test scripts

You can find cURL commands and Postman collections on our GitHub page.

These will give you examples of how to connect to our API. You can use the following cURL commands to simulate:

  • your software application’s actions and messages
  • the actions and messages that would come back from the NCTS

See IE015 cURL command

See IE016 cURL command

See Get Dept Id cURL command

If you are seeking examples of the XML requests to send to our service, you can find them in our repo on Github. You can find XML cURL files and Postman collection files.

If you want to use the XML directly, you can extract these from the files found in the Github repository either by using:

XSD files

You can access a full list of XSD reference files to check your XML files against our XSD files. Use these to validate your own XML.

  • You should note there are some known omissions in this XSD list
  • These are all listed in a mapping document so ensure you cross-reference this document when testing
  • You should also note that NumOfLoaLisHEA304 has been included in error in the following messages, and to ignore these:
    • IE015 (CC015B)
    • IE029 (CC029B)
    • IE043 (CC043A)
    • IE051 (CC051B)

Mapping document

You can access a mapping document containing plain English header descriptions, XML and EDIFACT code.

CTC Traders API Test Pack

You can download the latest CTC Traders API Test Pack to use when checking and testing your software is compatible with HMRC systems.

NCTS API technical interface specifications (TIS)

You can find all the NCTS API technical Interface specifications in one location.

Input (DTI) to NCTS This is where you can find a full list of messages, message content and sequence diagrams plus instructions on how to use test message transfer and content.

You should note that:

  • this is not the CTC Traders API technical specifications for Common Transit Convention
  • the CTC Traders API will be using XML and RESTful standards. It will not be using EDIFACT wrapper or SOAP
  • currently the TIS is tailored more towards the legacy systems and not the new CTC Traders XML API
  • we will revise and republish the CTC Traders API technical specifications for Common Transit Convention later in 2021 so bookmark this page to access them when they are published
  • you will find the TIS Appendices very useful. Appendix B Technical Message Structures will help you to check which data fields are optional and mandatory

Running test data sets

Once you have successfully run your tests using the test data exactly as is set out for each scenario, you can then run test data in any of the other fields.

There is an exception. You must not change the field data for the Consignor and Consignee details. These must remain the same and constant in every test you do otherwise your tests will fail. The same applies to the Guarantee data. This must remain constant and not be changed.

So for example, when testing message IE015 do not change the text which is BLOCK CAPITALS AND IN BOLD at all:

CONSIGNOR

Reference Description Data
CO1 Trader Name NCTS UK TEST LAB HMCE
Trader Street and Number 11TH FLOOR, ALEX HOUSE, VICTORIA AV
Trader Postal Code SS99 1AA
Trader City SOUTHEND-ON-SEA, ESSEX
Trader Country Code GB
Trader Name and Address Language Code EN
Trader EORI-TIN GB954131533000

CONSIGNEE

Reference Description Data
CE1 Trader Name NCTS UK TEST LAB HMCE
Trader Street and Number ITALIAN OFFICE
Trader Postal Code IT99 1IT
Trader City MILAN
Trader Country Code IT
Trader Name and Address Language Code EN
Trader EORI-TIN IT11ITALIANC11

GUARANTEE - REFERENCE

Reference Description Data
REF Guarantee Reference Number 09GB00000100000M0
Guarantee Access Code AC01
Guarantee Reference Amount £5.000.00 GBP

You can also use the reference data included in our Test Pack to run your software tests outside of the scope of the scenarios that we have listed. These will have limited support.

You must always remember to follow the same physical format for all data fields. For example, you could replace £5,000.00 guarantee amount to £11,000.00.

Checking API service availability

You can check planned API downtime or if there are technical issues:

If you find a bug

If you have found a bug in our code, you can get in touch with our developers directly on our GitHub Issues page.

Contact us for CTC API specific advice

  • If you have a specific question about the CTC Traders API, get in touch with our Software Developer Support Team. You’ll get an initial response in 2 working days
  • We are here to help with CTC Traders API questions and to support you
  • If we are not able to resolve your issue, we will find the help you need

Email us your questions at SDSTeam@hmrc.gov.uk or send an online enquiry. We might ask for more detailed information when we respond.

Submit your test results

Once you are satisfied with your tests and are confident that your software is fully compatible with our API:

  1. Log all your evidence and results by filling in all the sections of this checklist form (this is a word document which will download). You must also answer all the questions at the end of the checklist.
  2. When you are ready, email your completed form to SDSTeam@hmrc.gov.uk
  3. We will check your test evidence using the information you give on this form.
  4. When we are satisfied that you have done enough testing, you will be granted access to the live API system.

If you need further help and support

Email our dedicated software developer support team at SDSTeam@hmrc.gov.uk if you have any questions or difficulties or need additional clarification on this testing process.

For versioning information and a list of errors that you might receive please refer to the CTC Traders API Definition page.

Bookmark and save this page for future reference.