Introduction
On July 13, 2017, the Financial Secretary to the Treasury and Paymaster General in the United Kingdom announced that Making Tax Digital (MTD) for value-added tax (VAT) will take effect on April 1, 2019.
To support the MTD for VAT requirements on Dynamics AX 2012 R3 the hotfix was released: KB 4488588.
Additionally, Her Majesty's Revenue and Customs (HMRC) introduced compulsory to supply header information for VAT API from April 2019 to prevent fraud. For more information, see Fraud prevention. Fraud prevention headers in Dynamics AX 2012 R3 are supported with KB 4505299 and KB 4539848.
Overview
Current hotfix provides the following changes to the MTD VAT feature in Dynamics AX 2012 R3:
1. Include fraud prevention parameters parameter on General tab of Web service parameters form is always marked by default and disabled. This means that fraud prevention headers will always be sent as part of HTTPS requests to MTD VAT API of HMRC. It is not allowed to send requests to MTD VAT API of HMRC without fraud prevention headers. You can learn more about this requirement at Send fraud prevention data - HMRC Developer Hub.
2. Latest requirements to fraud prevention headers published by HMRC (Version 3.0) https://developer.service.hmrc.gov.uk/guides/fraud-prevention/getting-it-right/#change-log are now supported. Find more details later in this KB.
3. NewExternal web services to identify IP addresses form is introduced. It can be accessed by using External web services button on Fraud prevention tab of Web service parameters form. External web services to identify IP addresses form allows user (of System Administrator role) to specify HTTP(S) addresses of external web-services that return public IP address of client and server.
Notes:
-
(!) Privacy Notice
-
When you enable your Dynamics AX 2012 R3 to interoperate with Making Tax Digital (MTD) for Value Added Tax (VAT) API of Her Majesty’s Revenue and Customs (HMRC), both customer content and personal data will be shared with HMRC, as part of the submission of VAT information to the Making Tax Digital (MTD) for VAT report. This may include location information and other personal identifiers such as IP addresses. To learn more about the kinds of information that is included in your submission, you can view the HMRC requirements at the HMRC website. The interoperation with HMRC’s web service can be disabled by a System Administrator from within Web applications form by deactivating of the application of Production type.
Your privacy is important to us. To learn more read our Privacy and Cookies notice.
4. Populate button on Fraud prevention tab of Web service parameters form now creates only three headers: Gov-Client-Public-IP, Gov-Vendor-Public-IP, Gov-Vendor-Forwarded. User can still add other headers manually using Add/Remove buttons and specify values for them manually. These values will be used by the system only in the case when it was not possible to collect respective values automatically.
5. The algorithm of data collection for fraud prevention header has been changed: system collects information for the headers automatically and only in case it was not possible to collect a value for some of headers automatically, the manually defined values on Fraud prevention tab of Web service parameters form will be used for submission to HMRC.
Important:
-
(!) Note
-
On July 9, 2021 new client secret was generated for Dynamics AX 2012 R3 and published in Shared Asset library of LCS portal - UK_MTD_VAT_AX2012R3_ProdApll_20210709.zip. Go to Data package section of the Shared asset library to download the package to your local storage.
-
-
After you download UK_MTD_VAT_AX2012R3_ProdApll_20210709.zip from LCS, import the new client secret to your Dynamics AX 2012 R3 as it is explained in “Set up Web application for production use” paragraph of KB 4488588.
-
-
Make sure that access token can be successfully refreshed with the new secret. Use Refresh access token button on the Action pane of General ledger > Setup > External services > Web applications form in AX to manually initiate an access token refreshing.
-
Make sure that Active checkbox is marked for the web application of Production type, for which you have imported new client secret.
Hotfix details
“Include fraud prevention parameters” parameter
KB 4505299 introduced Include fraud prevention parameters parameter on General tab of Web service parameters form. Current update makes this parameter always marked by default and disabled. This means that fraud prevention headers will always be sent as part of your HTTPS requests to MTD VAT API of HMRC. It is not allowed to send requests to MTD VAT API of HMRC without fraud prevention headers. You can learn more about this requirement at Send fraud prevention data - HMRC Developer Hub.
Fraud prevention headers version 3.0
Latest requirements to fraud prevention headers, Version 3.0, published by HMRC https://developer.service.hmrc.gov.uk/guides/fraud-prevention/getting-it-right/#change-log are supported in Dynamics AX 2012 R3 with the current hotfix.
Find more details on how Dynamics AX 2012 R3 supports all the fraud prevention headers in the table below:
|
HTTP header |
Description |
Implementation details |
|
Gov-Client-Connection-Method |
Constant value: DESKTOP_APP_VIA_SERVER |
Constant value |
|
Gov-Client-Device-ID |
An identifier unique to an originating device. The format of the header was updated to accommodate latest requirement of HMRC. |
Automatically identified by the system using value from the system Registry: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HMRC |
|
Gov-Client-Local-IPs |
A list of all local IP addresses (IPv4 and IPv6) available to the originating device. |
Automatically identified by the system using System.Net.IPHostEntry and System.Net.IPAddress functionality. In case local IP addresses are not defined automatically, the constant value related to the "Gov-Client-Local-IPs" header will be collected from the "Set up supplemented fraud prevention headers" form and sent to HMRC. |
|
Gov-Client-Local-Ips-Timestamp |
A timestamp to show when Gov-Client-Local-IPs is collected. |
Automatically identified by the system as DateTime value in the format yyyy-MM-ddTHH:mm:ss.fffZ |
|
Gov-Client-MAC-Addresses |
The list of MAC addresses available on the originating device. |
Automatically identified by the system using:
|
|
Gov-Client-Multi-Factor |
A list of key-value data structures containing details of the multi-factor authentication (MFA) statuses related to the API call. |
Omitted for Dynamics AX 2012 R3. If your system supports MFA by using a customization, define necessary algorithm for the header to get it transferred correctly to HMRC. |
|
Gov-Client-Public-IP |
The public IP address (IPv4 or IPv6) from which the originating device makes the request. |
Automatically identified by calling External web services, that return value of public IP address. Find more information in “External web services to identify IP addresses” section of this KB article. |
|
Gov-Client-Public-Ip-Timestamp |
A timestamp to show when Gov-Client-Public-IP is collected. |
Automatically identified by the system as DateTime value in the format yyyy-MM-ddTHH:mm:ss.fffZ. |
|
Gov-Client-Public-Port |
The public TCP port that the originating device uses when initiating the request. |
Omitted for Dynamics AX 2012 R3. |
|
Gov-Client-Screens |
Information related to the originating device’s screens. The fields include (width of the screen, height of the screen, scaling factor of the screen, color depth of the screen). |
Automatically identified by the system using:
|
|
Gov-Client-Timezone |
The local time-zone of the originating device. |
Automatically identified by the system using xGlobal::machineTzDisplayName() |
|
Gov-Client-User-Agent |
An attempt to identify the operating system family, version, device manufacturer and model of the originating device. |
Automatically identified by the system by running the cmd.exe with commands:
|
|
Gov-Client-User-IDs |
A key-value data structure containing the user identifiers. |
Automatically identified by the system: WinAPI::getUserName() |
|
Gov-Client-Window-Size |
The number of pixels of the window on the originating device in which the user initiated (directly or indirectly) the API call to HMRC. |
Automatically identified by the system: WinAPI::getWindowRect |
|
Gov-Vendor-License-IDs |
A key-value data structure of hashed license keys relating to the vendor software initiating the API request on the originating device. |
Automatically identified and hashed by the system: xSysConfig::find(ConfigType::SerialNo, 0) |
|
Gov-Vendor-Product-Name |
The name of the product marketed to end users. |
Automatically identified by the system: xInfo::productName() |
|
Gov-Vendor-Public-IP |
The public IP address of the server to which the originating device sent their requests. |
Automatically identified by calling External web services, that return value of public IP address. Find more information in “External web services to identify IP addresses” section of this KB article. |
|
Gov-Vendor-Forwarded |
A list that details hops over the internet between services that terminate TLS. |
Automatically identified by the system as a value composed of values collected for Gov-Client-Public-IP and Gov-Vendor-Public-IP |
|
Gov-Vendor-Version |
A key-value data structure of software versions involved in handling a request. |
Automatically identified by the system: ApplicationVersion::buildNo()) |
External web services to identify IP address
Use newExternal web services to identify IP addresses form to define http(s) address(es) of web-services that will be called to obtain IP address of client and server and send it to the HMRC’s MTD API. Collected IP address of client and server are not saved in the system and sent to HMRC immediately after they are collected. Thus, when a business user initiates a request to HMRC (for example, to submit VAT return or retrieve VAT obligation information), system automatically (and hiddenly from the business user) sends request(s) to the external web-services defined in the External web services to identify IP addresses form to obtain public IP address of client and server. Obtained public IP address of client and server are immediately added to the business request’s headers (Gov-Client-Public-IP, Gov-Vendor-Public-IP, Gov-Vendor-Forwarded) and the request is transferred further to HMRC.
System administrator decides which external web-service can be used for the purpose of obtaining public IP addresses of client and server. Refer to the (!) Privacy Notice in the Overview section of this KB article. You can define several external web-services and they will be called consequentially in the order defined until IP address will be obtained in IPv4 or IPv6 format.
To define External web services, click External web services button in the Fraud prevention tab of Web service parameters form. In case public IP was not obtained from any external web-service, the constant value related to the "Gov-Client-Public-IP" header will be collected from the "Fraud prevention " tab and sent to HMRC.
‘Populate’ button on ‘Fraud prevention’ tab of ‘Web service parameters’ form
Populate button on Fraud prevention tab of Web service parameters form with the current hotfix creates only three headers: Gov-Client-Public-IP, Gov-Vendor-Public-IP, Gov-Vendor-Forwarded. User can still add other headers manually using Add and Remove buttons on the grid and specify values for created headers manually. These values will be used by the system only in the case when it was not possible to collect respective values automatically.
Algorithm of data collection for fraud prevention header
The algorithm of data collection for fraud prevention header has been changed. System collects information for the headers automatically and only in case it was not possible to collect a value for some of headers automatically, the manually defined values on Fraud prevention tab of Web service parameters form will be used for submission to HMRC.
We recommend using Validate button Fraud prevention tab of Web service parameters form to validate how your system is working to collect all the information for fraud prevention and make sure that values for all the fraud prevention headers are successfully collected. Only Gov-Client-Multi-Factor and Gov-Client-Public-Port headers are allowed to be omitted for Dynamics AX 2012 R3.
To be able to validate fraud prevention headers by using testing API of HMRC you must be registered on HMRC portal as a developer, create a sandbox application and subscribe it for “Test Fraud Prevention Headers API”. Find more information about fraud prevention headers validation from Dynamics AX 2012 R3 in KB 4539848.
