GS517 – Configuring UK MTD VAT Submission in D365FSCM – End-to-End Sandbox Setup and Validation Guide

Making Tax Digital (MTD) is a UK government initiative requiring VAT-registered businesses to keep digital records and submit VAT returns using compatible software. For businesses using Dynamics 365 Finance & Supply Chain, this means configuring a seamless, auditable integration with HMRC’s MTD gateway.

In this article, we’ll guide you step by step through setting up the full MTD VAT submission process in a sandbox (test) environment. This includes configuring electronic messaging, establishing the government connection, and simulating end-to-end VAT returns without writing a single line of code.

You’ll learn how to:

• Register and authenticate your HMRC sandbox application
• Configure application parameters in Dynamics 365
• Set up the Electronic Messaging framework for VAT returns
• Trigger test submissions and interpret HMRC responses
• Validate your configuration using real examples and logs

Whether you’re a consultant preparing a client for MTD compliance or a finance team testing your VAT return automation, this guide gives you a proven, audit-ready approach to UK MTD VAT submissions.

✅ Step 1: Import ER Configurations from Dataverse

1. Go to Workspaces > Globalisation Studio > Repositories > Microsoft, select Dataverse, and import the following 13 ER configurations files one by one, in order:

• After import, configurations will be accessible within ‘Reporting configuration’.

• Set the following default model mappings after import:
• Tax declaration model mapping

• MTD VAT model mapping

✅ Step 2: Configure Application Specific Parameters

The Application Specific Parameters setup in UK MTD VAT ensures that each transaction type—sales, purchases, credits, exemptions, or reverse charges—is correctly classified into VAT direction (e.g., payable, receivable) based on predefined conditions. By importing the ReportFieldLookup XML file, this classification logic is applied to both the JSON format (for HMRC submission) and Excel format (for internal review), ensuring consistency across reports. It enables automatic population of HMRC MTD boxes and supports audit readiness, making the VAT return process accurate, compliant, and efficient without custom coding.

JSON Format Parameters

1. Download the UK MTD VAT ReportFieldLookup v2.xml from the LCS Shared Asset Library.

2. Open Electronic Reporting > VAT Declaration JSON (UK) > Application specific parameters > Setup

3. Select the correct version and click Import

4. After import, set State to Completed

Conditions are now imported

Excel Format Parameters

1. We need to import same conditions for Excel format parameters too
2. Open VAT Declaration Excel (UK) > Application specific parameters > Setup

3. Select the correct version and click Import
4. Set State to Completed

✅ Step 3: Import Data Entities (Electronic Messaging Setup)

• Preload all the required MTD configuration records—such as electronic message processing actions, additional fields, and web service settings—into your Dynamics 365 Finance environment using a standardized data package. This ensures a consistent, error-free setup of the UK MTD VAT framework without manual data entry. It lays the foundation for interoperability with HMRC by importing preconfigured message structures and tax automation logic critical for VAT obligation retrieval and submission. Refreshing and synchronizing mappings ensures compatibility with your current environment schema.

1. Download the UK MTD VAT setup_v2.zip data package from LCS > Shared Assets Library.

2. Go to Data Management > Create Import project and select the package.
3. Modify target mapping → Generate mapping from scratch
4. Set Truncate entity data to Yes and import.

Note: Import may need to be run twice for complete success.

✅ Step 4: Configure General Ledger Parameters

Number Sequences

Number sequences is to define unique identifiers for electronic messages and their individual items within the MTD VAT processing framework. These number sequences ensure traceability, proper logging, and system consistency during message creation and tracking. Since each VAT return and obligation includes multiple messages and line items, distinct sequencing is required. Note that continuous number sequences are not supported, ensuring flexibility and reducing conflicts during message generation and reprocessing.

Configure under Tax > Setup > General ledger parameters > Number sequences tab:

• Message
• Message item

Excel VAT Report

VAT statement format mapping is to allow Dynamics 365 Finance to generate the VAT 100 report in Excel format using Electronic Reporting (ER), instead of the default SSRS version. By linking the VAT Declaration Excel (UK) format in General ledger parameters, users can produce a more user-friendly and auditable Excel version of the VAT return. This mapping is critical for environments using MTD, but it needs to be re-established after database refreshes, especially when moving from UAT  to PROD, as ER links to Excel files can break during environment copies.

Go to Tax > Setup > General ledger parameters > Sales tax tab, and select:

• VAT statement format mapping → VAT Declaration Excel (UK)

✅ Step 5: Define Sales Tax Settlement Periods

Defining Sales tax settlement periods in the Populate VAT return records action is to ensure that only the relevant VAT transactions from a specific settlement period are collected and reported to HMRC for MTD. Without this filter, Dynamics 365 would include all tax transactions from the legal entity, risking incorrect VAT returns. By setting the settlement period in the query of the data source setup, the system accurately isolates and populates transactions only for the defined reporting period, ensuring compliance and data integrity during VAT return generation.

1. Go to Tax > Setup > Electronic messages > Populate records actions

2. For action Populate VAT return records, define the applicable Sales tax settlement period

✅ Step 6: Assign Security Roles

Setting up security roles for Electronic messages processing is to control who can access and operate UK MTD VAT submissions in both sandbox and production environments. By assigning specific roles (e.g., Tax Accountant) to each processing definition (e.g., UK MTD VAT TEST or UK MTD VAT returns), you ensure only authorized users can initiate, generate, or submit VAT returns. Without assigning roles, only system administrators can access these processes, which can restrict operational flexibility and delay reporting. This setup aligns with security best practices and supports compliance auditing.

a. For Sandbox/Production Processing

1. Go to Tax > Setup > Electronic messages > Electronic message processing
2. Assign roles (e.g. Tax Accountant) to:
   • UK MTD VAT TEST
   • UK MTD VAT returns

For Access Token

Setting up security roles to access the token of a web application is to grant specific users or roles permission to interact with HMRC’s MTD services via the configured web application in Dynamics 365. This ensures that only authorized roles (e.g., Tax Accountant) can perform actions like requesting authorization codes or submitting VAT returns. If no roles are assigned, only system administrators can use the web application, which limits operational access. Assigning roles here supports secure, delegated access and aligns with role-based access control (RBAC) principles.

Go to Tax > Setup > Electronic messages > Web applications and assign roles to Sandbox and Production web apps.

✅ Step 7: Register Developer App on HMRC Dev Hub

Register your application on the HMRC Developer Hub so that it can communicate securely with HMRC’s MTD (Making Tax Digital) APIs. By creating an application and managing its API subscriptions, you enable it to access the required endpoints such as VAT submission and test user creation. This setup provides critical authentication details—Client ID, Client secret, and Server token—which are needed to authorize API requests from Dynamics 365. Setting the environment to Sandbox allows safe testing before going live. Adding the redirect URL ensures OAuth authentication flows work correctly.

Registration

1. Register at HMRC Developer Hub
2. Login (Note – Enable MFA is option but recommended)

Add an application

Manage API Subscription

1. API Subscription > Enable:
   • VAT (MTD) 1.0 (Beta)
   • Create Test User 1.0 (Beta)

2. Save credentials:
   • Client ID (Save offline)
   • Client Secret (Save offline)
   • Add Redirect URL: urn:ietf:wg:oauth:2.0:oob

✅ Step 8: Initialize Web Applications in D365FO

Initialize and configure your HMRC web application credentials within Dynamics 365 Finance so the system can authenticate and securely interact with HMRC’s MTD APIs. For the Sandbox, credentials (Client ID, Secret, Token) are manually entered for testing. For Production, credentials must be securely initialized using the InitProdWebAppl executable class and stored in encrypted format, ensuring compliance with HMRC security requirements. This setup is essential to enable OAuth-based authorization and allow the system to send VAT submissions or retrieve obligations from HMRC.

Sandbox App Setup

1. Fill in credentials under Tax > Setup > Electronic messages > Web applications
2. Ensure these fields are filled:
   • Base URL – https://test-api.service.hmrc.gov.uk           
   • Auth URL path – /oauth/authorize
   • Token URL path – /oauth/token
   • Redirect URL – urn:ietf:wg:oauth:2.0:oob

✅ Step 9: Get Authorization and Access Token

Simulate and authorize HMRC sandbox connectivity for UK MTD VAT testing in Dynamics 365 Finance. It involves generating a test user (User ID, Password, and VRN) using Electronic Messages, configuring the legal entity with the VRN, and obtaining an authorization code to securely link D365FO with HMRC’s sandbox environment. This setup ensures your system can send and retrieve test data using HMRC APIs in a controlled environment before going live in production. The authorization code is a mandatory OAuth step and is valid for only 10 minutes.

Create Test User

1. Go to – https://developer.service.hmrc.gov.uk/api-test-user

Obtain VRN (VAT Registration Number)

1. Save Username, Password and VRN (VAT Registration Number) details

Add VRN to Legal Entity

Setup Registration Type

Setup Registration Category

Add VRN in Legal entity Registration ID

• Go to legal entity > Registration ID

• Add Registration ID

Get Authorization Code

• Go to Web applications > Get Authorization code

• Add Scope – read:vat write:vat

• New browser tab opens – Allow D365 to connect with HMRC

• Ready to sign in with Test user we created above

• Enter Test user credentials

• Give Permission

• Authorization code generated – copy and save it

Note – Authorization code is valid for 10 minutes

Obtain Access Token

• Click on Obtain access Token

• Paste Authorization code copied above

• The Access token request is sent to HMRC, and D365FO automatically saves the Access token from HMRC’s response.

• Access tokens remain valid for 4 hours. When an access token expires, clicking the Refresh access token button generates a new token, which is then valid for another 4 hours.

 Step 10: Retrieve VAT Obligations

Retrieve a list of open and completed VAT obligations directly from HMRC using Electronic Messages in D365FO. This process allows the system to fetch period-specific VAT reporting obligations, synchronize them with Dynamics, and prepare for return generation. HMRC returns this data using a hidden periodKey, which is securely managed in the system. Based on the response, new electronic messages are automatically created or updated to reflect the correct reporting period, status, and due dates, ensuring accurate alignment between D365 and HMRC’s VAT timeline.

1. Go to Tax > Electronic messages
2. Create new message with action: Create VAT obligation request

3. Fill From date and To date.

From Date – Required. The start date of the period you want to check VAT obligations for

To Date – Required. The end date of the period you want to check VAT obligations for

Description – Optional. short note or title to describe this request.

4. Run Send report → obligations will be created or updated in the system

• Run Processing (Action is automatically defined)

• HMRC Response as below

HMRC tells us we’ve already submitted a VAT return for Jan–Mar 2017 and still have one open for Apr–Jun 2017. These dates appear because HMRC’s test system uses old dummy data.

Each VAT return has a hidden periodKey, which uniquely identifies the return period. D365 stores this key securely and hides it from users, as required by HMRC.

When importing VAT obligations:

• If a return is missing but required, it creates a new message.
• If a return is already submitted, it marks it as completed.
• If one exists, it updates its status and due dates based on HMRC’s reply

🏁 Conclusion

Once all the steps above are completed and tested using HMRC’s sandbox, your system is fully prepared to submit UK VAT returns using MTD in both test and live environments. You now have a robust, auditable, and secure electronic VAT process—end-to-end inside Dynamics 365 Finance.

📘 Coming Up Next

In GS518 – Integrating External APIs with Logic Apps and Electronic Reporting, we’ll show you how to go beyond standard setups and connect Dynamics 365 to external APIs—without writing code.
You’ll learn how to:

• Trigger an Azure Logic App from D365
• Send and parse JSON using ER formats
• Handle access token responses
• Log everything using Electronic Messaging

📖 Continue reading: GS518 – External API Integration →

🔍 View Full Article in PDF