Table of contents

Common Transit Convention Traders API end-to-end service guide


This guide explains how to use the new Common Transit Convention (CTC) Traders API with your software. The API will allow your software to send and receive movement notifications and status messages to and from the New Computerised Transit System (NCTS).

At the end of March 2021, you will be able to use the new CTC Traders API instead of the NCTS XML API channel for Common Transit arrivals and departures to and from Great Britain (GB), ie England, Scotland, Wales.

For timescales, see the CTC Roadmap.

We are updating this guide as we add more functionality to our API, new technical specifications.

Overview

The Common Transit Convention allows traders to move goods across CTC member states without paying import duties at every border they cross.

Under the agreement, CTC member countries only need to pay duties in the country of destination.

All goods will be subject to duties and other charges when they enter the EU, or enter the UK from the EU.

The API allows traders to send and receive arrival and departure notifications for CTC movements.

Replacing the NCTS XML API

Volumes of Common Transit movements are expected to increase significantly now that the UK is no longer part of the European Union. The current NCTS XML API channel needs to change to cope with this forecasted increase.

In order to make sure we provide a reliable and fast service we are introducing the new CTC Traders API to replace the current NCTS XML API.

If you have never used the NCTS XML API channel, you’ll only need to refer to the new CTC Traders API descriptions.

Comparison between the existing and the new API

The table shows how the new API uses different coding, compared to the existing NCTS XML API.

Activity NCTS XML API CTC Traders API
Submit Arrival Notification (IE007) SOAP authorisation (includes username and password in clear text) Government Gateway authorisation (OAuth 2.0 token)
Create action SOAP wrapper, with embedded instruction RESTful interface, action inferred from the URL
POST API Payload SOAP with EDIFACT body Information Exchange message (IE) XML
GET API Payload SOAP with EDIFACT body JSON and IE XML

Payloads comparison

The diagrams show the difference between the current EDIFACT and new XML payloads for GET and POST messages.

The current POST message payload consists of 4 layers:

  1. Outer layer: HTTPS
  2. Inside that: XML SOAP transport layer which includes
    • WSSE authentication, consisting of a clear text username and password
    • a command (eg getDocument)
  3. Within that: the EDIFACT ‘wrapper’
  4. At the centre: the true payload payload which is an XML list

The new POST payload message consists of 2 layers:

  1. Outer layer: RESTful standards HTTPS and OAuth 2.0 token authentication
  2. At the centre: the true payload which is an XML message eg IE007

The current GET message payload consists of 4 layers:

  1. Outer layer: HTTPS
  2. WIthin that: XML SOAP transport layer, which includes
    • WSSE authentication, consisting of clear text username and password
    • a command, eg getDocument
  3. Within that: the EDIFACT ‘wrapper’
  4. At the centre: the true payload - the GET message

The new GET payload consists of 3 layers:

  1. Outermost layer: RESTful standards HTTPS and OAuth 2.0 token authentication
  2. Middle layer: a JSON list
  3. At the centre: the true payload which is the XML

Advantages of the new CTC Traders API

  • Our systems will be ready for the expected increase in CTC movements
  • They will greatly improve security
  • Testing and maintenance of the platform will be more efficient

What you’ll need to do

Read the documentation

CTC Traders API specification

CTC Testing Guide

Using the Developer Hub

Testing your software

We have now released the API with working arrivals and departures endpoints for Great Britain only (and not Northern Ireland). You can now run tests for movements to or from Great Britain in HMRC’s sandbox environment.

First read the CTC Testing Guide. This signposts you to all the information you need and a step by step of what to do, plus the resources to use.

This will include:

  • All the information you need to get set up for testing
  • A link to the GB test pack with scenarios and test data
  • Detailed guidance for how to test

Trader Test will automatically simulate and give you responses just like in a real life scenario. You can also request NCTS support staff to generate the manual responses as if Border Force staff are processing your goods.

Validate your XML

Use our XSD files to validate your XML

Find out which functionality we’ve released

Check the roadmap to see what you can test now and what’s coming soon.

See the list of in-scope messages

Check which IE messages are applicable to the CTC Traders API.

Read about the current NCTS API channel specifications

The specifications for the current NCTS describe the business rules and logic for building software to connect with NCTS. These rules are applicable to both the current and the new APIs.

Visit the New Computerised Transit System: technical specifications to read about the NCTS system that’s currently in operation.

Note, this is the specification document for the outgoing NCTS XML API channel, so there will be discrepancies. For example, the CTC Traders API will not use an EDIFACT wrapper or SOAP.

Learn how to apply OAuth 2.0

Read guidance on the OAuth 2.0 standards required for HMRC APIs.

Use the Developer Hub tutorials

If you’re new to HMRC APIs, use the Developer Hub tutorials to find out what you need to know about working with us.

Get help

We have support in place to help you with any questions or problems you might have to do with the CTC Traders API. Find out to get help.

Check service availability

Before you get in touch, check out whether API downtime or technical issues are the problem. Check the HMRC API platform availability.

End-to-end process

The steps you need to take before you can use your software in the live environment:

  1. Register and subscribe to the Developer Hub Register for a developer account and subscribe to the CTC Traders API, Create Test User API and CTC PUSH/PULL notifications (to be released in February).
  2. Understand Government Gateway authorisation In order to use the CTC Traders API your software needs to interact using OAuth 2.0.
  3. Create test user To start testing your software, you need to generate test users.
  4. Download reference data To get Customs Offices List (COL) data to use for testing, visit the EU’s reference data download page.
  5. Apply to go live You need to apply for production credentials through your developer account.
  6. Get your customers ready For example, ask them to apply for an EORI number and a Government Gateway account.

Northern Ireland transit

Following the end of the UK’s transition from the EU, Northern Ireland transit movements (or NI movements) are handled slightly differently by the NCTS.

You can use the existing EDIFACT API channel and the email channel to submit departure and arrival messages for Northern Ireland NCTS instances. EDIFACT API messages will automatically be routed to the appropriate NCTS system without you having to make any changes to your software.

Later this year functionality will be available through the CTC API to submit NI movements. The exact date will be added to the Roadmap and we will email everyone who is subscribed to the CTC Traders API as soon it is available.

Message flows

Review the message flow diagrams to see the correct message sequences:

Changelog

Version 0.4: 10 February 2021 Added release date for the GB version of the API.

Version 0.3 11 September 2020 Added more XSD files and added to list of supported IE messages.

Version 0.2: 6 August 2020 Added further detail in reference to the XSD files.

Version 0.1: 15 July 2020 First release