Setup
When a
company is signed up for the MTD service for VAT in HMRC, to get Dynamics AX
2012 R3 ready to interoperate with HMRC web service for retrieving VAT obligations
and submission of VAT returns the following steps should be done in the Dynamics
AX 2012 R3:
·
Set
up Web service parameters
·
Set
up Web application for production use or testing interoperation with HMRC's sandbox
· Obtain Authorization
code
·
Get Access token and activate application
Set up Web service parameters
Open General ledger > Setup > External services > Web
service parameters form.
Use this
form to define following parameters of the Web service:
|
Field
|
Description
|
Value example
|
|
Sandbox base URL
|
When
a sandbox web application is created on HMRC side, define its base URL https
address.
|
|
|
Production base URL
|
When
your HMRC account is setup on production application, define its base URL
https address.
|
|
|
Authorization URL path
|
Set
up authorization URL path used for HMRC web application.
|
/oauth/authorize
|
|
Token URL path
|
Set
up token URL path used for HMRC web application.
|
/oauth/token |
Set up Web application for testing
Open General ledger > Setup > External services > Web applications
form.
Use this
form to define following parameters of a Web application:
|
Field
|
Description
|
|
Application name
|
Type
a name of the application. It can be the name of the application in HMRC or
any other you choose to identify the application in AX.
|
|
Description
|
Fill
in a description of the application.
|
|
Application type
|
Select
Sandbox, if you are going to use
this application for testing purposes connecting to an HMRC’s sandbox.
Depending
on this type system will use either Sandbox
base URL address of the Web-service.
|
|
Settlement period
|
Select
AX Sales tax settlement period for
which VAT returns must be submitted using this Web application.
Only
one Sales tax settlement period
can be selected for each Web
application.
|
|
Client ID
|
Type
Client ID of the Web application. This parameter is
related to a set of HMRC application parameters and can be found in Manage credentials section of an
application in HMRC portal.
|
|
Client secret
|
Type
Client secret of the Web application. This parameter is
related to a set of HMRC application parameters and can be found in Manage credentials section of an
application in HMRC portal.
|
|
Redirect URL
|
Type
Redirect URL of the Web application. This parameter is
related to a set of HMRC application parameters and can be found in Manage redirect URIs section of an
application in HMRC portal.
|
|
Access token will expire in
|
This
is a read-only field which shows when the last received access token will
expire. This field is updated automatically when an access token is received
from HMRC.
|
|
Scope
|
This
is a read-only field which shows a scope which was requested from HMRC for
the application during initial authorization for the application.
User
must fill in this value manually on HMRC authorization.
The
following values are allowed by HMRC:
-
read:vat
-
write:vat
-
read:vat write:vat
It
is recommended to use “read:vat
write:vat” as the same application must be used for both GET and POST
https requests to the web service.
|
Create Test user
This function
is available for applications of Sandbox type only. Click on Get test user button on the Action pane
of Web applications form to create a
test user which can be used to access HMRC’s sandbox environment. Type Server
token of your testing application in the dialog and click OK. Server token is a
parameter of an HMRC’s application. It can be found in Manage credentials section of your testing HMRC’s application on
HMRC portal. When you click OK button of the dialog, a request for test user is
sent to HMRC and a response is received. You will be able to see the response
in Test user
data form in AX. Don’t close this form until you get an Authorization
code as information in it will be requested by HMRC to sign in on getting HMRC
authorization. Following three parameters from this response will be further
used:
-
User ID - you will copy and paste it during sing in on
HMRC portal for Authorization code retrieving.
-
Password - you will copy and paste during sing in on
HMRC portal for Authorization code retrieving.
-
VRN – will be saved automatically in AX. This VAT
registration number will be used for testing interoperation with HMRC.
To be able
to create a test user, Create test user
API must be activated for your HMRC’s application. To do so, open Manage API subscriptions section for
your testing application in HMRC portal and activate Create test user API in Test
Support APIs.
Obtain Authorization code
Authorization
code is needed to request an Access token. Authorization code received from
HMRC is valid only 10 minutes within which an Access token can be requested. If
an Access token is not requested and Authorization code has expired, a new
Authorization code must be requested.
Click HMRC authorization button on the Action
pane of Web applications form to get
an Authorization code from HMRC. It is recommended to type “read:vat write:vat” in Scope field of the dialog so the
application could be allowed for both GET and POST https requests. Click OK to
send your Authorization code request to HMRC. You will be redirected to HMRC
sign in web page. Click Continue
button and use you company’s User ID
and Password granted during HMRC
online account registration for production web application authorization. For Sandbox application, copy
and paste User ID and Password from the Test user data form in AX which you received from HMRC on Test user creation stage:
![]()
Copy Authorization code created by HMRC and
go back to AX to initialize getting of Access token during 10 minutes.
Get Access token and activate application
Initialize
getting of Access token during 10 minutes from the moment an Authorization code was generated by
HMRC.
Click Get access token button on the Action
pane of Web applications form to
request an Access token form HMRC. Past value copied on the previous “Obtain Authorization code” step to the Authorization code field of the
dialog and click OK. Access token request will be sent to HMRC and an Access
token will be automatically saved in AX from the HMRC’s response. It is not
allowed to review the token from user interface of AX. You can observe validity
period of Access token in Access token
will expire in field. Each Access token is valid during 4 hours from the
moment when it was created by HMRC. To receive a new one, you don’t need to
renew an Authorization code. For this purpose, you need to Refresh access
token.
When Access token is granted, mark Active field of the application to use
this application for further interoperation with HMRC. Only one Web application can be active for each Sales tax settlement period. System
will not allow to activate a Web application before an Access token is received
from HMRC.
Refreshing access token
Each Access
token is valid during 4 hours from the moment when it was created by HMRC.
Click on Refresh access token button on the
Action pane of Web applications form
to manually initiate refreshing of an access token. Refresh Access token
request will be sent to HMRC and a new Access token will be automatically saved
in AX from the HMRC’s response.
It is not needed to refresh token manually each
4 hours or before you start to interoperate with HMRC. During interoperation
with HMRC this refreshing Access token procedure will be initialized
automatically and refreshing of Access token will be hidden from user.
Set up Web
application for production use
When a company is ready to interoperate with MTD for
VAT in live, it must sign up to MTD and create a HMRC online account (Government Gateway account) unless
one already exist. The company will then need to link it to the Microsoft
Dynamics AX 2012 R3 application by selecting Microsoft Dynamics AX 2012 R3
as the software. The company will then obtain user credentials (User ID and
password) that are linked to its VAT registration number:
· User
ID – The name that is used to access HMRC while an authorization code is
being requested.
· Password
– The password that is used to access HMRC while an authorization code is being
requested
After the company has obtained user credentials an
application of Production type can be setup on AX side. Application of
production type is uniquely identified by Client ID and Client secret
and are provided by Microsoft (unless the company is creating their own
solution for any Dynamics AX version). The following steps must be done on AX
side to setup the application of Production type:
1. Open LCS portal, go to Shared asset library:
2. Select Data package section and find latest (by
Modified date) version of UK_MTD_VAT_AX2012R3_ProdApll.zip file,
download this file on your computer:
3. Open in Dynamics AX 2012 R3 General ledger >
Setup > External services > Web applications form
and create a new record. Fill in fields:
|
Field
|
Description
|
|
Application name
|
Type a name of the application. It can be any name you
choose to identify the application in AX.
|
|
Description
|
Fill in a description of the application.
|
|
Application type
|
Select “Production” when you create an
application for production usage which you are going to use for real-life
submission of VAT returns to HMRC.
|
|
Settlement period
|
Select AX Sales tax settlement period for
which VAT returns must be submitted using this Web application.
Only one Sales tax settlement period can be
selected for each Web application.
|
|
Redirect URL
|
Type “urn:ietf:wg:oauth:2.0:oob” in this
field.
|
4. Click “Initialization of production application”
button on the Credentials fast tab:
5. Select previously downloaded from LCS portal UK_MTD_VAT_AX2012R3_ProdApll.zip
file. Don’t unzip the file. Click OK button and production application
credentials will be populated to the system:
6. Client ID and Client
secret of production application are populated in your system in encrypted
format:
When web application of production type is setup in AX,
authorize it to get ready to interoperate with HMRC:
1. Open General ledger > Setup > External
services > Web applications form and select web application of
production type for which Client ID and Client secret are
imported.
2. Click HMRC authorization button on the Action
pane to obtain Authorization code from HMRC for the selected web application, specify
“write:vat read:vat” in Scope field and click OK:
3. A web browser will be opened, and you will be directed
on HMRC portal for authorization. Authorize on the page with User ID and
Password, which were obtained for your company via online account on
HMRC. As a result, an Authorization code will be generated and shown on
the browser page.
4. Copy Authorization code and open General
ledger > Setup > External services > Web
applications form in AX again. Authorization code is valid only 10
minutes within which an Access token can be requested. If an Access token
is not requested and Authorization code has expired, a new Authorization code
must be requested.
5. Click Get access token button in General
ledger > Setup > External services > Web
applications form in AX and paste Authorization code copied on the
previous step. Each Access token is valid during 4 hours from the moment
when it was created by HMRC. To receive a new one, you don’t need to renew an
Authorization code. For this purpose, you need to Refresh the access token.
6. As a result, an Access token will be granted by
HMRC and saved in your system. You will see “Access token expire in” and
“Scope” fields are filled in for the selected web application of
production type.
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.
7. Activate the web application by setting Active check-box for the related web application:
When you have set Active a web application of production type, your system is ready to interoperate with HMRC for VAT MTD in live.
Retrieving VAT obligations
from HMRC
When Web service parameters are setup and Web application is created and
activated, system is ready to interoperate with HMRC.
(!) Important note: VAT registration number (VRN) of the legal entity must be defined in Organization
Administration > Legal Entities, on the Foreign trade and
logistics tab, in the "VAT exempt number export” field. This field is
used as a VRN source for VAT 100 report and MTD-feature, respectively.
Open General ledger > Periodic > Sales tax payments > United
Kingdom > VAT returns submission form.
This form presents information about VAT obligations and returns and serves for
interoperation with HMRC web service.
|
Field
|
Description
|
|
Start date
|
Start
date of an accounting period in HMRC.
|
|
End date
|
End
date of an accounting period in HMRC.
|
|
HMRC status
|
Reporting
status of an accounting period in HMRC. It can be either Open or Fulfilled.
|
|
Period key
|
VAT
obligation related to an accounting period in HMRC is identified in HMRC by
value of Period key field. This field is not shown on the form and must be hidden from the user interface to complete the requirement of the HMRC.
|
|
Settlement period
|
AX
Sales tax settlement period set up for the Web application. VAT return will
be calculated basing on Sales tax transactions posted in this Sales tax
settlement period.
|
|
Status
|
AX
internal Status of VAT obligation.
It can be either:
-
Created
-
Generated
-
Submitted
-
Error.
|
|
Due date
|
The
due date for this obligation period. This field is updated from HMRC only.
|
|
Received date
|
The
obligation received date. This field is updated from HMRC only when VAT
obligation is fulfilled.
|
|
VAT return
|
This
field shows generated VAT return in JSON format. User can review calculated
amounts before their submission to HMRC.
|
|
Sales tax payment version
|
This field shows value of Sales tax payment
version parameter with which VAT return was generated.
|
|
Processing date
|
The
date when the VAT return was processed in the HMRC. This field is updated
from HMRC only when VAT obligation is fulfilled.
|
|
Payment indication
|
Is “DD”
if the netVatDue value is a debit and HMRC holds a Direct Debit Instruction
for the client. Is “BANK” if the netVatDue value is a credit and HMRC holds
the client’s bank data. Otherwise not present. This field is updated from
HMRC only when VAT obligation is fulfilled.
|
|
Form bundle number
|
Unique
number that represents the form bundle. The HMRC system stores VAT Return
data in forms, which are held in a unique form bundle. This field is updated
from HMRC only when VAT obligation is fulfilled.
|
You may
review all the actions done with a VAT obligation on the Log fast tab.
VAT
obligations must be received first from the HMRC. Click Retrieve VAT obligations button on the Action pane.
|
Field
|
Description
|
|
Settlement period
|
Select
AX Sales tax settlement period in this field. This must be a Sales tax
settlement period for which you want to get your VAT obligations and further
submit VAT return. This parameter defines the Web application in the system to be used to interoperate with HMRC.
|
|
Start date
|
Select
the date starting from which you want to retrieve VAT obligations from HMRC.
|
|
End date
|
Select
the end date of a period for which you want to retrieve VAT obligations from
HMRC.
|
An active Web application set up for the Sales
tax settlement period will be used for interoperation with HMRC. If this
application is of “Sandbox” type,
you will see an additional dialog with Test
scenario field. Define one of testing scenario supported by HMRC (see
Manage API subscriptions > APIs > VAT > Endpoints > Retrieve VAT
obligations > Test data section of HMRC related to your testing application,
to find all the Gov-Test-Scenario). For example, you can type “QUARTERLY_NONE_MET”
in this field to simulates the scenario where the client has quarterly
obligations and none are fulfilled. You may leave this field blank to initiate
“Default” testing scenario which simulates the scenario where the client has
quarterly obligations and one is fulfilled. Click OK button. Your request to
HMRC will be sent and response received. According to the response, new records
in VAT returns submission form will
be created or existing updated.
Generate VAT return in
JSON
MTD for VAT
accepts VAT returns in JSON format only. To generate VAT return in JSON format select
a record on VAT returns submission
form related to the obligation period you are going to report. Click on Generate VAT return button on the
Action pane of VAT returns submission
form. Select in Sales tax payment
version field of the dialog one of the values similarly to you select on Sales tax payments report generation:
-
Original
-
Corrections
-
Latest
corrections
-
Total
list.
Click OK.
VAT return in JSON format will be generated and available for review in VAT return field.
You may
regenerate VAT return several times until you submit it to HMRC.
Submitting VAT returns to
HMRC
When VAT
return in JSON format is generated and ready to be submitted to HMRC, click on Submit VAT return button on Action pane
on the VAT returns submission form.
VAT return can be submitted to HMRC just once for each obligation period. Make
sure you want to submit VAT return before click YES in AX warning box. Warning
box includes declaration that the user by clicking “Yes” button confirms that
the information which is going to be submitted to HMRC is true and complete.
Accepting this declaration by “Yes” button user is responsible for the submitted
information. If you are not sure that VAT return is ready to be submitted,
click NO. When you click YES, generated VAT return in JSON format related to
the selected record in VAT returns
submission form will be submitted to HMRC. If VAT return is submitted
successfully to HMRC its status will be updated respectively to Submitted. HMRC status, Received date field in AX will be updated if you retrieve VAT
obligations for a period including the reported one. In case of any error
during submission of VAT return to HMRC, Status
will be updated to Error.
You may
review all the actions done with a VAT obligation on Log fast tab of the VAT
returns submission form. When a response is received from HMRC you may
review its full text by View full
response button. In case of error, Error
code field will show a code of error from response and Error description field will show description of error from the
response.
Security privileges
Following
security privileges are created for the new functionality:
|
Security privilege
|
Description
|
Associated with
|
|
Setup
and get HMRC access tokens (TaxHMRCSetupMaintain_UK)
|
Edit Web service parameters,
Web applications (including Get test user, HMRC authorization, Get
access token, Refresh access token)
Access Level:
- TaxHMRCApplication_UK
{delete}
- TaxHMRCParameters_UK
{delete}
- TaxHMRCApplicationAuthorization_UK
{delete}
- TaxHMRCTestUserData_UK {delete}
- TaxHMRCHelper_UK
methods (getAccessToken) {invoke}
|
Duty: Maintain sales tax
transactions (TaxSalesTaxTransactionsMaintain)
|
|
Retrieve
HMRC VAT obligation (TaxHMRCVATObligationRetrieve_UK)
|
Retrieve VAT obligations on the
form VAT returns submission
Access Level:
- TaxHMRCApplication_UK
{read}
- TaxHMRCVATObligation_UK
{correct}
- TaxHMRCHelper_UK
methods (retrieveVATObligations) {invoke}
|
Duty:
Maintain sales tax transactions (TaxSalesTaxTransactionsMaintain)
|
|
Generate
HMRC VAT return (TaxHMRCVATObligationGenerate_UK)
|
Generate VAT return on the form VAT
returns submission
Access Level:
- TaxHMRCVATObligation_UK
{correct}
- TaxHMRCHelper_UK
methods (generateVATReturn) {invoke}
|
Duty: Maintain sales tax
transactions (TaxSalesTaxTransactionsMaintain)
|
|
Submit
HMRC VAT return (TaxHMRCVATObligationSubmit_UK)
|
Submit VAT return on the form VAT
returns submission
Access Level:
- TaxHMRCApplication_UK
{read}
- TaxHMRCVATObligation_UK
{correct}
- TaxHMRCHelper_UK
methods (submitVATReturn) {invoke}
|
Duty:
Maintain sales tax transactions (TaxSalesTaxTransactionsMaintain)
|
|
View
HMRC VAT obligation (TaxHMRCVATObligationView_UK)
|
View VAT returns submission form.
Access Level:
- TaxHMRCVATObligation_UK
{read}
|
Duty: Inquire into sales tax
transaction status (TaxSalesTaxTransactionStatusInquire)
|
To review
or change distribution of security privileges by security duties and roles,
open System administration > Setup > Security > Security roles.