• sa.global recognized as Finalist for the 2019 Media & Communications Partner of the Year Award

    sa.global recognized as Finalist for the 2019
    Media & Communications Partner of the Year Award

    Learn More

    sa.global recognized as Finalist for the 2019 Media & Communications Partner of the Year Award

    Learn More

Interact with MTD VAT APIs using POSTMAN

Making Tax Digital (MTD) is the UK Government’s initiative to simplify and transform the tax systems with digital records for VAT. Making Tax Digital for VAT came into effect in April 2019 and is applicable to individuals and businesses with a turnover above the VAT threshold. It affects how businesses and individuals maintain their accounting and tax records and how they transact and communicate with HM Revenue and Customs (HMRC).

With MTD, all VAT submissions must be made digitally through the MTD API on the new portal. This is where the MTD VAT API software comes in. It allows individuals and businesses to supply business financial data to HMRC. It helps organizations interact using programming languages and other tools; POSTMAN is one such tool that helps interact with these APIs.

This blog aims at:

  1. Helping you understand how OAuth 2 works.
  2. Assisting you to directly view if the actual HMRC site/APIs are working as expected.
  3. Helping you view more descriptive messages in case of errors.

Here is how you can interact using MTD VAT API. Please note that the steps below are preferred for Sandbox environment only. Prerequisites.

Prerequisites.

  1. Install POSTMAN. ( Refer: https://dl.pstmn.io/download/latest/win64 or https://www.getpostman.com/downloads/)
  2. Get access to HMRC Developer Hub https://developer.service.hmrc.gov.uk/developer/applications/
    OR
    Get details of the environment like:
    • Client ID
    • Client secrets
    • Server token
    • Redirect URI
  3. Refer: https://developer.service.hmrc.gov.uk/api-documentation/docs/authorisation/user-restricted-endpoints

If you are new to POSTMAN and would like to learn how you can send an API request, use the link below: https://learning.getpostman.com/docs/postman/sending_api_requests/requests
Once you get familiar with the basic usage of POSTMAN, start with the steps below:

Step 1: Create a sandbox user -User ID, Password with Vat Return Number

Method Post: https://test-api.service.hmrc.gov.uk/create-test-user/organisations

Headers
Content-Type: application/json
Accept: application/vnd.hmrc.1.0+json
Authorization: Bearer 3####################3 (This value should be Server Token from HMRC Site)
Body
{
"serviceNames": [
"mtd-vat"
]
}
Click on Send
Notice the response looks as shown below
{
"userId": " 380699039642",
"password": "qfnLYfPcxImS",
"userFullName": "Gale Quinn",
"emailAddress": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"organisationDetails": {
"name": "Company YVGNSW",
"address": {
"line1": "37 Kentish Town Road",
"line2": "Marlow",
"postcode": "TS5 1PA"
}
},
"vrn": " 666694412"
}

Step2: Generate “Authorization Code” for the user created in Step1

• Ping this URL in IE
https://test-api.service.hmrc.gov.uk/oauth/authorize?response_type=code&client_id=H##########a
&scope=read:vat+write:vat&redirect_uri=http://l#########0&state=12345

Note: Edit the value for ClientID and redirect Uri as per the environment setup made in HMRC sight
• Click ‘Continue’
• Provide User ID and Password from Step1.
Sign-In and click Grant Authority
• You should receive below link
http://localhost/?code=e6afff69cc8445cda50ad8ea50a3c3bf&state=12345

Step 3: Generate “Access Token Key” from the code received from Step 2

Method POST: https://test-api.service.hmrc.gov.uk/oauth/token
Headers
Content-Type: application/json
Accept: application/vnd.hmrc.1.0+json
Body
{
"client_id": "H#################a",
"client_secret": "d###############2,"
"grant_type": "authorization_code",
"redirect_uri": "http://l#############0",
"code": "e6afff69cc8445cda50ad8ea50a3c3bf"
}
Note: Edit code value received in Step 2 along with the value for ClientID, Client Secret and Redirect Uri as per the environment setup made in HMRC sight
Click to send the request
You will get: Response
{
"access_token": "c3927165293c383f3723cabfc14b1730",
"refresh_token": "fc15c1116312d8c9a7c248cc3d0bb",
"expires_in": 14400,
"scope": "read:vat write:vat",
"token_type": "bearer"
}

Step 4: Retrieve Obligation for the user created in Step1 with the “Access Token Key” received from Step3 (for the VAT number from step1)

Method GET: https://test-api.service.hmrc.gov.uk/organisations/vat/ 666694412/obligations
Note: Vat Number highlighted is the one received from Step1
Headers
Content-Type: application/json
Accept: application/vnd.hmrc.1.0+json
Authorization: Bearer c3927165293c383f3723cabfc14b1730 (This value should be the Access Token value received from Step3)
Params
from 2017-01-01
to 2017-12-31
Click on send the request
Response:
{
"obligations": [
{
"start": "2017-01-01",
"end": "2017-03-31",
"due": "2017-05-07",
"status": "F",
"periodKey": "18A1",
"received": "2017-05-06"
},
{
"start": "2017-04-01",
"end": "2017-06-30",
"due": "2017-08-07",
"status": "O",
"periodKey": "18A2"
} ]
}
For next request: note (use period Key received in above request)

Step 5: Submit VAT return for specific period (for the VAT number from step1)

Method post: "https://test-api.service.hmrc.gov.uk/organisations/vat/666694412/returns
Note: Vat Number highlighted is the one received from Step1
Headers
Content-Type: application/json
Accept: application/vnd.hmrc.1.0+json
Authorization: Bearer c3927165293c383f3723cabfc14b1730 (This value should be the Access Token value received from Step3)
Body
{
"periodKey": "18A2",
"vatDueSales": 100.00,
"vatDueAcquisitions": 100.00,
"totalVatDue": 200.00,
"vatReclaimedCurrPeriod": 100.00,
"netVatDue": 100.00,
"totalValueSalesExVAT": 500,
"totalValuePurchasesExVAT": 500,
"totalValueGoodsSuppliedExVAT": 500,
"totalAcquisitionsExVAT": 500,
"finalised": true
}
Note: The Period Key Value should match with the one of the values received in Step4
Click to send the response
Response
{
"processingDate": "2018-10-26T05:48:29.265Z",
"paymentIndicator": "DD",
"formBundleNumber": "476464446033",
"chargeRefNumber": "AMKzeYdRhhdV5SNp"
}

About the Author

Radhika Pujari

Radhika Pujari

Radhika Pujari is a thoughtful mind who researches on technologies to bring ideas to reality. She has over nine years of experience in Analysis, Designing, and Development of Microsoft Dynamics GP, NAV, and Business Central product solutions. She also has expertise in extending these ERPs to truly utilize the power of the Microsoft Power Platform. Her current area of interest is in exploring Artificial Intelligence and its integration with ERP.
  • This email address is being protected from spambots. You need JavaScript enabled to view it.
Contact Us

Select Country

Select Your Local Website

Other Websites










sa.global does not share your personal data with any third parties.
I'm ok with sa.global storing my personal information as per their privacy policy