United Kingdom: Making Tax Digital - fraud prevention headers on Dynamics 365 for Finance and Operations

Applies to: Dynamics 365 for Finance and Operations

Introduction


On July 13,2017, the Financial Secretary to the Treasury and Paymaster General in theUnited Kingdom announced that Making Tax Digital (MTD) for value-added tax(VAT) will take effect on April 1, 2019.

Dynamics365 for Finance and Operations starting from version 10.0.1 supports MTD forVAT of the United Kingdom.

To supportthe MTD for VAT requirements on Dynamics 365 for Finance and Operations version7.3 the hotfixes were released: #4492999,#4493076.

Thedocumentation about setting up and usage Dynamics 365 for Finance andOperations for MTD for VAT is published on https://docs.microsoft.com/en-us/dynamics365/unified-operations/financials/localizations/emea-gbr-mtd-vat-integration.

Additionally,HM Revenue and Customs (HMRC) introduced compulsory to supply headerinformation for VAT API from April 2019 to prevent fraud. For more information,see Fraud prevention.

Overview


To preventfraud, APIs of the HMRC provide HTTP headers that must be used to pass auditdata.

Dependingon the architecture of the environment used by a company which interoperateswith the MTD for VAT different set of HTTP headers for fraud prevention must betransmitted. “Gov-Client-Connection-Method” header must represent theconnection method used for the request by the company. It is supposed that mostcompanies using Dynamics 365 for Finance and Operations in cloud architecture use“WEB_APP_VIA_SERVER” connection method during interoperation with HMRC via Electronic messages functionality. It is also possible that auser may initiate a batch job for interoperation with HMRC, in this case connectionmethod will be transmitted as “BATCH_PROCESS_DIRECT”. 

WEB_APP_VIA_SERVER” connection method assumes transmission of the followingheaders:

HTTP header

Description

Coverage

Gov-Client-Public-IP

The public IP address (IPv4 or IPv6) from which the originating device makes the request.

Not in scope of the current hotfix.

Gov-Client-Public-Port

The public TCP port that the originating device uses when initiating the request.

Not in scope of the current hotfix.

Gov-Client-Device-ID

An identifier unique to an originating device.

Not in scope of the current hotfix.

Gov-Client-User-IDs

A key-value data structure containing the user identifiers.

Not in scope of the current hotfix.

Gov-Client-Timezone

The local time-zone of the originating device.

Not in scope of the current hotfix.

Gov-Client-Local-IPs

A list of all local IP addresses (IPv4 and IPv6) available to the originating device.

Not in scope of the current hotfix.

Gov-Client-Screens

Information related to the originating device’s screens. The fields include:

  • width is the reported width of the screen, in pixels
  • height is the reported height of the screen, in pixels
  • scaling-factor is the reported scaling factor of the screen.
  • color-depth is the color depth of the screen, in bits.

Not in scope of the current hotfix.

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.

Not in scope of the current hotfix.

Gov-Client-Browser-Plugins

A list of browser plugins on the originating device.

Not in scope of the current hotfix.

Gov-Client-Browser-JS-User-Agent

JavaScript-reported user agent string from the originating device.

Not in scope of the current hotfix.

Gov-Client-Browser-Do-Not-Track

Whether the Do Not Track option is enabled on the browser.

Not in scope of the current hotfix.

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.

Not in scope of the current hotfix.

Gov-Vendor-Version

A key-value data structure of software versions involved in handling a request.

Included into the current hotfix.

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.

Not in scope of the current hotfix.

Gov-Vendor-Public-IP

The public IP address of the servers to which the originating device sent their requests.

Not in scope of the current hotfix.

Gov-Vendor-Forwarded

A list that details hops over the internet between services that terminate TLS.

Not in scope of the current hotfix.

BATCH_PROCESS_DIRECT” connection methodassumes transmission of the following headers:

HTTP header

Description

Coverage

Gov-Client-Device-ID

An identifier unique to an originating device.

Not in scope of the current hotfix.

Gov-Client-User-IDs

A key-value data structure containing the user identifiers.

Not in scope of the current hotfix.

Gov-Client-Timezone

The local time-zone of the originating device.

Included into the current hotfix.

Gov-Client-Local-IPs

A list of all local IP addresses (IPv4 and IPv6) available to the originating device.

Not in scope of the current hotfix.

Gov-Client-User-Agent

An attempt to identify the operating system family, version, device manufacturer and model of the originating device.

Included into the current hotfix.

Gov-Vendor-Version

A key-value data structure of software versions involved in handling a request.

Included into the current hotfix.

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.

Not in scope of the current hotfix.

Gov-Client-MAC-Addresses

The list of MAC addresses available on the originating device.

Included into the current hotfix.


Implementation details


To supportpossibility of detecting parameters required by fraud prevention requirementsof the HMRC like time-zone and MAC address in BATCH_PROCESS_DIRECT connectionmethod and version of the software in both WEB_APP_VIA_SERVER and BATCH_PROCESS_DIRECT connection methods,an X++ methods were included into the application part. Here is the informationabout versions of Dynamics 365 for Finance and Operations including thesemethods:

Dynamics 365 for Finance and Operations version

Build number

10.0.1

10.0.51.30002

10.0.2

10.0.80.10022

10.0.3

10.0.107.0

For versions 7.3 of Dynamics 365 for Financeand Operations the KB # 4504462 must be installed.

In Dynamics 365 for Finance and Operations requestheaders are composed by the “MTD VAT web request headers format (UK)” formatin Electronic Reporting (ER) module. To support fraud prevention headers thisformat configuration was extended with necessary nodes:

image.png

Determination of the corresponding values ofthe headers is supported via calling of the X++ methods by the “MTD VATmodel mapping” configuration. “Electronic Messages framework model”was also extended to include nodes used for mapping of the values offraud prevention headers.

Setup


To activatetransmission of fraud prevention headers during interoperating with API of theHMRC, import the following of higher versions of the following ERconfigurations from the LCS portal:

#

GER configuration name

Type

Version

1

Electronic Messages framework model

Model

22

2

MTD VAT model mapping (UK)

Model mapping (exporting, importing)

22.25

3

MTD VAT web request headers format (UK)

Format (exporting)

22.13


Important note!  When new versions of ER configurations are imported, check that followingconfigurations are marked as Default formodel mapping:

  • Taxdeclaration model mapping
  • MTD VAT model mapping (UK)

When mentionedor higher versions of the ER configurations are imported, fraud preventionparameters will be transmitted as part of the HTTP request the HMRC.

When userinitiates a request to the HMRC without activating a batch job, the followingdialog will inform about what information is going to be sent to the HMRC:

image.png

If the user aborts the transmission on this stage by clicking the Cancel button ofthe dialog, transmission will be canceled and the status of the electronicmessage will be changed to “Error”, attached description of the error to theAction log will include information that the “Request to the HMRC is cancelled byuser”. User will be able to proceed with transmission of the same electronic messageusing “Send report” button.

When userinitiates a request to the HMRC in a batch job, the fraud prevention headerswill be transmitted to the HMRC and information about what headers were sentwill be attached to the batch job. Open System administration > Inquires > Batch jobs, select yourbatch job and review Message details of the Log (Action pane > Batch job > Log).

If for somereason a company decides to address requests to the HMRC without transmittingfraud prevention headers, the version of the format including the fraudprevention headers can be deleted or not imported at all or alternatively theseheaders can be disabled in the “MTDVAT web request headers format (UK)” in Electronic Reporting module. Forthis purpose, the following steps must be done:

  1. Select “MTD VAT web request headers format (UK) in the configurations tree of the ERand create a child format by Deriving it (see more about “Buildinga format selecting another format as a base”).
  2. Open the child format in theDesigner (Designer button the Action pane of ER).
  3. Select “Gov-Client-Connection-Method” node and set “Enabled”parameter to “false”:
image.png
4. Repeat p.3 for other fraud prevention headers: Gov-Client-Timezone,Gov-Client-User-Agent, Gov-Vendor-Version, Gov-Client-MAC-Addresses.
5. Save yourconfiguration and Complete it.
6. Open Tax > Setup> Electronic reporting > Web service settings and selectyour child format in the “Request headers format mapping” field of allthe web services used for interoperation with the HMRC instead of the parentformat used by default:
image.png

Importantnote!  API requests without fraud prevention headersmay be rejected by HMRC. It is strictly recommended to address API requests toHMRC with fraud prevention headers.

Hotfix information


How to obtain the Microsoft Dynamics AX updates files

This update is available for manual download and installation from the Microsoft Download Center for version 7.3:

Prerequisites

You must have one of the following products installed to apply this hotfix:

  • Microsoft Dynamics 365 for Finance and Operations (7.3)

Restart requirement

You must restart the Application Object Server (AOS) service after you apply the hotfix.

If you are encountering an issue downloading, installing this hotfix, or have other technical support questions, contact your partner or, if enrolled in a support plan directly with Microsoft, you can contact technical support for Microsoft Dynamics and create a new support request. To do this, visit the following Microsoft website:

https://mbs.microsoft.com/support/newstart.aspx

You can also contact technical support for Microsoft Dynamics by phone using these links for country specific phone numbers. To do this, visit one of the following Microsoft websites:

Partners

https://mbs.microsoft.com/partnersource/resources/support/supportinformation/Global+Support+Contacts

Customers

https://mbs.microsoft.com/customersource/northamerica/help/help/contactus

In special cases, charges that are ordinarily incurred for support calls may be canceled if a Technical Support Professional for Microsoft Dynamics and related products determines that a specific update will resolve your problem. The usual support costs will apply to any additional support questions and issues that do not qualify for the specific update in question.