Metadata-Version: 2.4
Name: ct600
Version: 1.4.6
Summary: UK HMRC Corporation Tax submission
Author-email: Cybermaggedon <mark@cyberapocalypse.co.uk>
Project-URL: Homepage, https://github.com/cybermaggedon/ct600
Project-URL: Download, https://github.com/cybermaggedon/ct600/.0.tar.gz
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp
Requires-Dist: py-dmidecode
Requires-Dist: requests
Requires-Dist: ixbrl-parse
Requires-Dist: pyaml
Dynamic: license-file


# `ct600`

## Introduction

A utility for managing UK Corporation Tax submission.

## Caveat

This probably won't do what you want, unless you are prepared to do a fair
amount of work and data validation.  It works for me, and my workflow
running a small business.

I am registered as an HMRC developer and requested credentials for live
submission.  To use this code you need to go through the same process.

## Overview

This code is intended to be used with the following workflow:
- Previously, you will have created company accounts, and corporation tax
  computations filing in iXBRL format.
- The first step is to use `ct600` to create what I am calling a
  "form values" file.  This is a text file with 1 line for each CT600 box
  that you would fill in.  This process is partly automated, it takes
  as input the Computations iXBRL and fills in some basic CT600 fields.
  For my small business with no loss to record, this step produces
  a form values file which is mostly ready to use.
- The second step is to modify the form values file to match what you
  want to submit.  You need a text editor to do this.
  You definitely need to add boxes 975, 980 and 985
  (name, date, status) because these aren't filled in for you.
- The final step is to submit the accounts, computations and CT600 data
  in the forms values files.

### Input: iXBRL files

See [Company Tax Returns](https://www.gov.uk/company-tax-returns) and
[Corporation Tax online: support for software developers](https://www.gov.uk/government/collections/corporation-tax-online-support-for-software-developers)

This is based on my understand of HMRC's requirements, this is not advice you
should use in isolation.  Go and read the documentation above.

The accounts file needs to match what HMRC expect.  `ct600` does not parse
this file in any way, so it just needs to match what HMRC expect, which is
basically you submit what you would be submitted to Companies House
at annual filing.

The tax computations file needs to include computations data as well as
detailed profit and loss (DPL).

I use [`ixbrl-reporter-jsonnet`](https://github.com/cybermaggedon/ixbrl-reporter-jsonnet) to create iXBRL files from GnuCash.

### Creating a form values file

The command is of the form:

```
ct600 --computations ct.html --output-form-values > form-values.yaml
```

You can skip this step and create the form values file manually if you want,
but doing it this way provides a way to validate that the computations file
matches what is in the form values file.

The output will contain a field for every single box in the CT600 form,
most of which will be blank.  You can delete the blank lines if you want.

### Modifying the form values file

You will probably need to have access to the published CT600 form, and
guidance for completing it.  We're not actually going to be filling in the
form here, just making sure the form values file contains a value for
all the boxes you want to fill in.

See [CT600](https://www.gov.uk/government/publications/corporation-tax-company-tax-return-ct600-2015-version-3)

## Configuration

Configuration is a JSON file passed via `--config`.  Three config files are
provided for different scenarios:

| File | Purpose | `gateway-test` | `class` | `url` |
|---|---|---|---|---|
| `config-test.json` | Local testing | `"1"` | `HMRC-CT-CT600-TIL` | `http://localhost:8081/` |
| `config-til.json` | Test-In-Live (real HMRC, test data) | `"0"` | `HMRC-CT-CT600-TIL` | HMRC production |
| `config-prod.json` | Production (real submission) | `"0"` | `HMRC-CT-CT600` | HMRC production |

All three contain placeholder credentials — replace `username`, `password`
and `vendor-id` with your own before use.

> **Warning:** `config-prod.json` submits real tax returns. Do not use it
> unless you intend to file.

You can also create your own `config.json` — it is gitignored and will not
be committed.

### Safe defaults

If a config file omits these fields, the defaults are safe:

| Field | Default |
|---|---|
| `url` | `http://localhost:8081/` |
| `class` | `HMRC-CT-CT600-TIL` |
| `gateway-test` | `"1"` |

Running with an incomplete config will never accidentally hit production HMRC.

### Config file fields

```json
{
    "company-type": 6,
    "declaration-name": "Sarah McAcre",
    "declaration-status": "Director",
    "username": "govidgoeshere",
    "password": "passwordgoeshere",
    "gateway-test": "1",
    "class": "HMRC-CT-CT600-TIL",
    "vendor-id": "1234",
    "url": "http://localhost:8081/",
    "title": "Ms",
    "first-name": "Sarah",
    "second-name": "McAcre",
    "email": "sarah@example.org",
    "phone": "447900123456"
}
```

## Submission

There are three ways to test and submit, in order of risk.

### 1. Local test service (recommended first step)

This is optional and slightly involved to set up, but it is the recommended
way to get a feel for how the whole submission process works without touching
HMRC at all.

The package includes a basic corptax emulator with schema validation.
Install the package, then run:

```
corptax-test-service
```

In a separate terminal, submit to it using `config-test.json`:

```
ct600 \
    --config config-test.json \
    --accounts accts.html \
    --computations ct.html \
    --form-values form-values.yaml \
    --submit
```

Expected output:
```
IRmark is hOgMwO+75eJbBax/OhPZy/NszxE=
Correlation ID is 1E242
Endpoint is http://localhost:8082/
Poll...
Poll...
Poll...
Poll...
Submitted successfully.
Delete request...
Completed.
```

### 2. Test-In-Live (real HMRC, test data)

Test-In-Live submits to the real HMRC endpoint using the `HMRC-CT-CT600-TIL`
message class.  HMRC accepts and validates the submission but does not
process it as a real tax return.  If the submission is successful, you
also get an email confirming this.  I think this is sent to the email
address associated with the HMRC account.

You need real Government Gateway credentials (`username` and `password`)
for this — these are the same credentials you use to log in to HMRC online
services.

> **Warning:** Government Gateway credentials are stored in clear text in
> the config file.  Do not commit them to version control.  Use your own
> `config.json` (which is gitignored) or be careful with `config-til.json`.

The required config settings are:

| Field | Value |
|---|---|
| `gateway-test` | `"0"` |
| `class` | `HMRC-CT-CT600-TIL` |
| `url` | `https://transaction-engine.tax.service.gov.uk/submission` |

These are already set in `config-til.json`.

```
ct600 \
    --config config-til.json \
    --accounts accts.html \
    --computations ct.html \
    --form-values form-values.yaml \
    --submit
```

### 3. Production

> **Warning:** This submits a real Corporation Tax return to HMRC.
> Make sure your data is correct before submitting.

You need real Government Gateway credentials, as with Test-In-Live.
The same warning about storing credentials in clear text applies.

The required config settings are:

| Field | Value |
|---|---|
| `gateway-test` | `"0"` |
| `class` | `HMRC-CT-CT600` |
| `url` | `https://transaction-engine.tax.service.gov.uk/submission` |

These are already set in `config-prod.json`.

```
ct600 \
    --config config-prod.json \
    --accounts accts.html \
    --computations ct.html \
    --form-values form-values.yaml \
    --submit
```

The output is verbose.  You'll know if the submission was successful.

If there are errors, the output is not parsed particularly well, but there
will be clues about what the errors are.

If the submission works, you can use this repo to take the form values
file and overlay the data on a CT600 PDF file as a record of what you
submitted:

https://github.com/cybermaggedon/ct600-fill

## Installing

```
pip3 install .
```

## Credentials

For Test-In-Live and production filing, the `username` and `password` in
your config file are just your Government Gateway credentials — the same
ones you use to log in to HMRC online services.  You do not need to
register as a developer to use Test-In-Live or to file live returns.

The `vendor-id` is a developer credential.  I am registered as an HMRC
developer and have been issued a vendor ID.  HMRC does not permit these
credentials to be shared publicly.

HMRC also provides separate test systems intended for developers.  You
should only use these if you have been given access through the developer
hub:

https://developer.service.hmrc.gov.uk/api-documentation/docs/using-the-hub

## Usage

```
usage: ct600 [-h] [--config CONFIG] [--accounts ACCOUNTS]
             [--computations COMPUTATIONS] [--form-values FORM_VALUES]
             [--attachment ATTACHMENT] [--output-ct] [--output-values]
             [--output-form-values] [--submit] [--data-request]

Submission to HMRC Corporation Tax API

options:
  -h, --help            show this help message and exit
  --config CONFIG, -c CONFIG
                        Configuration file (default: config.json)
  --accounts ACCOUNTS, -a ACCOUNTS
                        Company accounts iXBRL file
  --computations COMPUTATIONS, --comps COMPUTATIONS, -t COMPUTATIONS
                        Corporation tax computations iXBRL file
  --form-values FORM_VALUES, --ct600 FORM_VALUES, -f FORM_VALUES
                        CT600 form values YAML file
  --attachment ATTACHMENT, -m ATTACHMENT
                        Corporation tax computations iXBRL file
  --output-ct, -p       Just output CT message, no submission
  --output-values       Just output some data values (debug)
  --output-form-values  Output CT600 form values from computations
  --submit              Submit the CT message
  --data-request        Perform a data request for outstanding items
```

# Licences, Compliance, etc.

## Warranty

This code comes with no warranty whatsoever.  See the [LICENSE](LICENCE) file
for details.  Further, I am not an accountant.  It is possible that this code
could be useful to you in meeting regulatory reporting requirements for your
business.  It is also possible that the software could report misleading
information which could land you in a lot of trouble if used for regulatory
purposes.  Really, you should check with a qualified accountant.

## Licence

Copyright (C) 2020-2026, Cyberapocalypse Limited

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

## Support

You're welcome to come discuss on Discord

https://discord.gg/3cAvPASS6p
