Submit a VAT return to HMRC's MTD web service

Note

Community interest groups have now moved from Yammer to Microsoft Viva Engage. To join a Viva Engage community and take part in the latest discussions, fill out the Request access to Finance and Operations Viva Engage Community form and choose the community you want to join.

This article explains how to submit a value-added tax (VAT) return to the Making Tax Digital (MTD) web service of His Majesty's Revenue and Customs (HMRC) in Microsoft Dynamics 365 Finance.

Note

• To meet security requirements, we implemented modifications to the Dynamics 365 Finance direct system-to-system integration with the HMRC web service for submitting VAT returns for companies registered for VAT in the UK. This enhancement involves the adoption of an Electronic Invoicing service as an intermediary that facilitates secure access to the storage of credentials essential for software authorization within the HMRC APIs. These services won't be accessible from on-premises deployments by June 6, 2025.
• As of June 6, 2025, batch mode for submission of VAT returns in the Making Tax Digital feature isn't supported. You can still generate in batch the report (VAT 100) in Excel and JSON formats.

Important

• We recommend enabling the Security enhancements in UK MTD VAT integration (cloud-based deployments only) feature to activate the implemented security enhancements and comply with Microsoft security requirements.
• Learn about the transition of cloud-based deployments to the Security enhancements in UK MTD VAT integration (cloud-based deployments only) feature in Security enhancements in UK MTD VAT integration (cloud-based deployments only).
• When you enable the Security enhancements in UK MTD VAT integration (cloud-based deployments only) feature, you don't need to manually start the authorization workflow on the Web application page for your Microsoft Dynamics 365 Finance environment to interoperate with the HMRC's Making Tax Digital (MTD) web service. The authorization workflow is triggered automatically when required during a VAT obligation request or VAT return submission.

Prerequisites

When your company is registered for VAT and ready to interoperate with MTD VAT in a production environment, you must create an HMRC online account if it doesn't already exist. This account is also known as a Government Gateway account. Next, link the online account to the Finance application by selecting Microsoft Dynamics 365 Finance as the MTD-compatible software. You get a user ID and password and link them to your VAT registration number:

• User ID – The name that you use to access HMRC while requesting an authorization code.
• Password – The password that you use to access HMRC while requesting an authorization code.

After you obtain your user credentials, you can use the MTD VAT feature from within your Finance.

Overview

Important

When you use the MTD VAT feature that Microsoft provides, you don't need to request production credentials from HMRC. Microsoft automatically supplies all the required web application credentials (Client ID and Client secret) when you use this feature. When you enable the Security enhancements in UK MTD VAT integration (cloud-based deployments only) feature, the system stores the web application credentials in a Microsoft-managed Key Vault and retrieves them during a VAT obligation request or VAT return submission.

The process of submitting a VAT return has two parts:

1. VAT obligation retrieval

   The following illustration shows a simplified representation of the processing for VAT obligation retrieval that Electronic messages implements in the scope of the UK MTD VAT returns processing.

   

2. VAT return submission

   The following illustration shows a simplified representation of the processing for VAT return submission that Electronic messages implements in the scope of the UK MTD VAT returns processing.

   

Retrieve VAT obligations from HMRC

After you enable the Security enhancements in UK MTD VAT integration (cloud-based deployments only) feature in your Finance environment, your environment is ready to work with MTD endpoints of HMRC.

Before you submit a VAT return, you must retrieve VAT obligations from HMRC. To retrieve VAT obligations from HMRC, follow these steps:

1. In Dynamics 365 Finance, go to Tax > Inquiries and reports > Electronic messages > Electronic messages, and select the UK MTD VAT returns processing.

2. On the Messages FastTab, select New.

3. In the Run processing dialog, in the Action field, select Create VAT obligation request. Then select OK. A new electronic message is created that has a status of New obligation request.

4. Set the following fields.

   Field	Description
   From date	This field is mandatory for electronic messages that retrieve VAT obligations. Specify the start date of the period for which you want to get information about VAT obligations from HMRC.
   To date	This field is mandatory for electronic messages that retrieve VAT obligations. Specify the end date of the period for which you want to get information about VAT obligations from HMRC.
   Description	This field is optional for electronic messages that retrieve VAT obligations. Enter a description of the electronic message.

   The Action log FastTab saves information about the user who created the electronic message, and the date and time when the electronic message was created.

   No other fields are applicable to this type of electronic message.

5. Select Send report to initialize the retrieval of VAT obligation information from HMRC.

6. In the Run processing dialog, the Retrieve VAT obligations action is automatically defined, and information is filled in by the system. Select OK.

7. In the Request identification information dialog, select the checkbox to consent to providing the information in fraud prevention headers as part of the VAT request to HMRC. Then select Submit. Your privacy is important to us. To learn more, read our privacy notice.

   A request in JavaScript Object Notation (JSON) format is created and sent to HMRC. The response that is received from HMRC is attached to the electronic message. Based on the response, either new electronic messages for the VAT return are created, or existing electronic messages are updated.

The last step of the processing is an Import VAT obligations action of the Electronic reporting import type. The system defines the following behavior for this step:

• If a VAT obligation from the response doesn't exist in the database, and the status of that VAT obligation in HMRC is Open, a new electronic message is created that has a status of New VAT return.
• If a VAT obligation from the response doesn't exist in the database, and the status of that VAT obligation in HMRC is Fulfilled, a new electronic message is created that has a status of Completed VAT return.
• If a VAT obligation from the response exists in the database, the system verifies the values of the HMRC status, Due date, and Received date additional fields. It then syncs those values with the information from the response.

All the actions that are performed for electronic messages are logged and can be viewed on the Action log FastTab.

Important

HMRC uniquely identifies each VAT return period by using a periodKey parameter. This parameter is stored in Finance. However, according to HMRC requirements, users must not be able to see the periodKey value in the user interface (UI). Therefore, the periodKey additional field is used to store the periodKey value in UK MTD VAT returns processing. This field is set up as a hidden field, so that users can't see its value. To ensure compliance with HMRC requirements, don't change this setup for the periodKey additional field.

The following illustration shows the lifecycle of electronic message processing for the retrieval of VAT obligations.

When you use the UK MTD VAT returns processing for the first time, you see the System administrator consent dialog. Select the checkbox to confirm that you want to enable interoperation with HMRC's MTD application programming interface (API) and use external web services and select Agree to continue or Disagree to cancel. Once consent for the system administrator agreement is granted, this dialog doesn't appear again for subsequent requests related to the specified electronic message processing. Your privacy is important to us. To learn more, read our privacy notice.

You're automatically redirected to HMRC's web portal for authorization if your current authorization has expired or if you're using the integration for the first time within the specified legal entity in Finance. To continue working with HMRC's APIs follow these steps:

1. Select Continue.

Note

The system doesn't initiate the authorization step if you previously authorized the integration for the specified legal entity in Finance and the authorization is still valid. The authorization is valid for 100 days, after which you must reauthorize every 100 days.

1. In the HMRC portal for authorization, on the Sign in page, enter the User ID and Password values that you obtained from HMRC during your subscription for MTD. Then select Sign in.

   

2. Select Grant authority.

3. The Authorization granted page shows the authorization code that HMRC granted to you for your Finance environment. Copy this authorization code to the clipboard.

Important

An authorization code is valid for only 10 minutes. You must proceed with the next steps during that time. Otherwise, the authorization code expires. In that case, you can use the same test user credentials to get a new authorization code.

1. In your browser, switch to the Finance page where you're working with electronic messages. You should see a dialog that includes an Authorization code parameter. Paste the authorization code that you copied as the value of this parameter. Then select OK to continue.
2. In this step, the authorization is completed, and the VAT obligation request starts.

Collect data for a VAT return

The process of preparing and submitting a VAT return for a period is based on sales tax payment transactions that the Settle and post sales tax job posts. For more information about sales tax settlement and reporting, see Sales tax overview.

Before you start to prepare and submit a VAT return to HMRC, complete the regular Settle and post sales tax job for the period that you want to report to HMRC. When you run this job, it creates new sales tax payment transactions. To view these sales tax payments, go to Tax > Inquiries and reports > Sales tax Inquiries > Sales tax payments. You can review the resulting values for each sales tax payment transaction on the VAT 100 report in Excel format.

You can run the Settle and post sales tax job several times for the same period before you submit a VAT return to HMRC. You can include all the sales tax payment transactions on the same VAT return report for a period. The transactions that the system fills in for reporting depend on the sales tax settlement period that you define in the Populate VAT return records action for the processing. You can also include sales tax payment transactions from several legal entities in one VAT return that you report as a VAT group. For more information, see Define a sales tax settlement period.

Important

MTD VAT lets you submit a VAT return only one time for each reporting period. As HMRC states on the official website, the current amendment process remains in place for VAT:

• If the net value of the errors on the VAT return is less than £10,000, the company amends those errors on the next VAT return.
• If the net value of the errors exceeds £10,000, the company must complete the VAT 652 form, which is available on the Gov.UK website.

When the Settle and post sales tax job completes, you can prepare a report for electronic submission. The first step of data preparation is to collect sales tax payment transactions that relate to the period.

To collect sales tax payment transactions, follow these steps:

1. In Dynamics 365 Finance, go to Tax > Inquiries and reports > Electronic messages > Electronic messages, and select the UK MTD VAT returns processing.
2. On the Message FastTab, select the electronic message that relates to the period that you want to submit a VAT return for. Don't update the Start date and End date fields of the record. The system receives those values from HMRC and uses them as criteria for collecting sales tax payment transactions. You can enter a description of the electronic message. You can collect VAT data only for electronic messages that have a status of New VAT return.
3. On the Message FastTab, select Collect data to start collecting sales tax payment transactions.
4. In the Run processing dialog, the Populate VAT return records action is predefined. Select OK.
5. The system collects the sales tax payment transactions that you posted in the period that you defined in the From date and To date fields. Next, the system enters those transactions as electronic message items of the message. You can review the transactions on the Message items FastTab.
6. If, for some reason, a sales tax payment transaction that the system entered must be excluded from the report, you can delete it. Alternatively, you can update its status to Excluded by selecting Update status on the Message items FastTab. Transactions that have a status of Excluded aren't considered for reporting. You can also change the status of a transaction from Excluded back to Populated by selecting Update status on the Message items FastTab.
7. You can repeatedly select Collect data on the Message FastTab until the electronic message moves to the next status.
8. After data is collected, select Update status on the Messages FastTab.
9. In the Update status dialog, the Ready to generate VAT return status is predefined. Select OK to mark the electronic message as ready for report generation. The status of the electronic message items that are linked to the electronic message is updated to To be reported.
10. If, for some reason, you must go back to step 3 and continue to collect data or change the status of electronic message items, select Update status on the Messages FastTab, select New VAT return in the New status field, and then select OK.

The Action log FastTab saves information about all the actions that you perform for the electronic message.

After an electronic message has a status of Ready to generate VAT return, you can initialize report generation. Two options are available:

• Preview VAT return – The file is generated in Excel format and attached to the electronic message. No statuses are changed.
• Generate file for submission – The file is generated in JSON format and attached to the electronic message. The status of the electronic message is updated to Generated VAT return, and the status of the linked electronic message items is updated to Reported.

Generate a VAT return in Excel format for preview

To generate a VAT return in VAT 100 report format in Excel, follow these steps:

1. In Dynamics 365 Finance, go to Tax > Inquiries and reports > Electronic messages > Electronic messages, and select the UK MTD VAT returns processing.

2. On the Messages FastTab, select the electronic message record that relates to the period that you want to generate a file for, and then select Generate report. The Generate report button is available only for electronic messages that have the following statuses:

   • Ready to generate VAT return – The user changes the electronic message status to this value by selecting Update status.
   • Error VAT return generation – If an error occurs during report generation, the electronic message status changes to this value.
   • Error VAT return submission – If an error occurs during report submission, the electronic message status changes to this value. The response that includes a description of the error is attached to the action log.

3. In the Run processing dialog, select Preview VAT return, and then select OK. The file is generated in Excel format and attached to the electronic message. No statuses change.

4. To view the file, select the electronic message, then select Attachments (the paper clip symbol) in the upper-right corner of the page.

5. On the Attachments page for the selected message, select the last attachment (VAT statement.xlsx) then on the Action Pane, select Open. The file opens in Excel.

You can regenerate the VAT 100 report several times before you generate the report in JSON format. At that point, the electronic message status changes to Generated VAT return.

Generate a VAT return in JSON format

HMRC's MTD VAT API accepts VAT returns in JSON format only.

To generate a VAT return in JSON format, follow these steps:

1. In Dynamics 365 Finance, go to Tax > Inquiries and reports > Electronic messages > Electronic messages, and select the UK MTD VAT returns processing.
2. On the Messages FastTab, select the electronic message record that relates to the period for which you want to generate a file, then select Generate report.
3. In the Run processing dialog, select Generate file for submission, then select OK. The system generates the file in JSON format and attaches it to the electronic message. The system updates the electronic message status to Generated VAT return and updates the status of the linked electronic message items to Reported.
4. To view the file, select the electronic message, then select Attachments (the paper clip symbol) in the upper-right corner of the page.
5. On the Attachments page for the selected message, select the last attachment (VAT_return.json) then on the Action Pane, select Open.

If you need to regenerate a VAT return in JSON format before submitting it to HMRC, select Update status on the Messages FastTab to update the status of the related electronic message to either New VAT return or Ready to generate VAT return, depending on whether you need to return to the data collection step or the file generation step.

Submit VAT returns to HMRC

When you generate a VAT return in JSON format and it's ready to submit to HMRC, initialize its submission to the MTD VAT web application. The last JSON file that you attached to the electronic message is used for the submission. To help prevent discrepancies, delete any unnecessary JSON files that you attached to the electronic message that you submit to HMRC. To find and clean up unnecessary attachments, select the electronic message, then select Attachments (the paper clip symbol) in the upper-right corner of the page. The Attachments page for the selected message opens.

To submit a VAT return, follow these steps:

1. In Dynamics 365 Finance, go to Tax > Inquiries and reports > Electronic messages > Electronic messages, and select the UK MTD VAT returns processing.

2. On the Messages FastTab, select the electronic message record that is related to the period that you want to submit the VAT return for, then select Send report. The Send report button is available only for electronic messages that have the following statuses:

   • Generated VAT return – The electronic message status is automatically updated to this value when a VAT return in JSON format is successfully generated and attached to the electronic message.
   • Error VAT return submission – If an error occurs during report submission, the electronic message status changes to this value. The response that includes a description of the error is attached to the action log.

3. In the Run processing dialog, the Submit VAT return action is predefined. Select OK.

4. The dialog that appears contains mandatory declaration text that HMRC requires. To remain compliant with HMRC requirements, don't modify or delete this declaration text in the setup of the Submit VAT return action. By selecting OK in this dialog, you submit VAT information, and you confirm that the information is true and complete. A false declaration can result in prosecution.

   You can submit a VAT return to HMRC only one time for each period. Therefore, make sure that you want to submit the VAT return before you accept the declaration. If you aren't sure whether the VAT return is ready to be submitted, select Cancel.

   When you select OK, the VAT return in JSON format that is related to the selected electronic message is submitted to HMRC. If the VAT return is successfully submitted to HMRC, the status of the electronic message is updated to Sent VAT return, and the response from HMRC is attached to the electronic message.

5. In the Request identification information dialog, select the checkbox to consent to providing the information in fraud prevention headers as part of the VAT request to HMRC. Then select Submit. Your privacy is important to us. To learn more, read our privacy notice.

   The system automatically runs the Import response for VAT return action. This action causes the Processing date additional field of the electronic message to reflect information from the response. Additionally, the system updates the status of the electronic message to Completed VAT return and updates the status of the electronic message items to Submitted.

   If, for some reason, the Import response for VAT return action isn't automatically run, you can manually initialize it by selecting Import response on the Messages FastTab. The Import response button is available only for electronic messages that have a status of Sent VAT return. The electronic message status is automatically updated to this value when a VAT return in JSON format is successfully submitted to the electronic message.

The Action log FastTab saves information about all the actions that you perform for the electronic message.

You're automatically redirected to HMRC's web portal for authorization if your current authorization has expired or if you're using the integration for the first time within the specified legal entity in Finance. To continue working with HMRC's APIs follow these steps:

1. Select Continue.

Note

The system doesn't initiate the authorization step if you previously authorized the integration for the specified legal entity in Finance and the authorization is still valid. The authorization is valid for 100 days, after which you must reauthorize every 100 days.

1. In the HMRC portal for authorization, on the Sign in page, enter the User ID and Password values that you obtained from HMRC during your subscription for MTD. Then select Sign in.

   

2. Select Grant authority.

3. The Authorization granted page shows the authorization code that HMRC granted to you for your Finance environment. Copy this authorization code to the clipboard.

Important

An authorization code is valid for only 10 minutes. You must proceed with the next steps during that time. Otherwise, the authorization code expires. In that case, you can use the same test user credentials to get a new authorization code.

1. In your browser, switch to the Finance page where you're working with electronic messages. You should see a dialog that includes an Authorization code parameter. Paste the authorization code that you copied as the value of this parameter. Then select OK to continue.
2. In this step, the authorization is completed, and the VAT return submission starts.

Submit VAT returns to HMRC from on-premises deployments of Dynamics 365 Finance

Starting June 6, 2025, support for the UK MTD VAT integration feature in on-premises deployments of Dynamics 365 Finance is discontinued.

Transitioning to the cloud deployment of Dynamics 365 Finance offers several advantages. These advantages include enhanced security, automatic updates, and compliance with HMRC's MTD requirements. This transition provides seamless integration and access to the latest Dynamics 365 Finance features.

Additionally, you can use a cloud-based environment as intermediary software for submitting your VAT return to HMRC from your on-premises deployment. To implement this solution, establish a cloud-based environment configured to interact seamlessly with your existing systems.

With adjustments to the UK MTD VAT Electronic Messaging, you can efficiently submit your VAT returns to HMRC using Dynamics 365 Finance's cloud-based solution. This approach allows your organization to benefit from cloud capabilities such as more security options, improved data management, and staying updated with regulatory changes. We recommend this option to ensure compliance with HMRC's VAT submission requirements.

To adopt the UK MTD VAT Electronic Messaging to submit a VAT return in JSON format generated in your on-premises deployments of Dynamics 365 Finance, follow these steps:

1. Set up your cloud environment to integrate with HMRC as explained in the following sections of Prepare your environment to interoperate with HMRC's MTD VAT web service article.
   • Import and set up ER configurations.
   • Set up application-specific parameters for MTD VAT web request headers format.
   • Import a package of data entities that includes a predefined EM setup.
   • Set up the VAT registration number of the company that's reporting VAT.
   • Set up number sequences for Electronic messages functionality.
   • Set up document management parameters.
   • Set up security roles for electronic message processing.
   • Set up security roles to interoperate with HMRC's MTD VAT web service.
2. Authorize your cloud environment to interoperate with HMRCs MTD web service as explained in Authorize your Finance environment to interoperate with HMRC's MTD web service.
3. Modify the UK MTD VAT returns Electronic message processing as follows.
   1. Go to Tax > Setup > Electronic messages > Message processing actions, select the Ready to generate VAT return action and change the Result status to Generated VAT return. After this change, the Ready to generate VAT return action expects that a preliminary generated JSON file is attached to the electronic message. After the Ready to generate VAT return action is executed, the JSON file from the attachment can be submitted by running the Submit VAT return action.
   2. Go to Tax > Setup > Electronic messages > Electronic message processing and select the UK MTD VAT returns on the left side of the page. Select and remove from the list the following action: Populate VAT return records, Exclude from reporting, Preview VAT return, and Generate file for submission.

With these changes to the 'UK MTD VAT returns' electronic message processing, you can use your cloud-based Dynamics 365 Finance to submit a VAT return generated in your on-premises Dynamics 365 Finance instance in JSON format by attaching the JSON file to the electronic message in the Ready to generate VAT return action.