{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"9154d680-6787-40f7-9627-f625e0b9a803","name":"For Taxpayers-GRA E-VAT API - VER 8.2","description":"This document (GRA E-VAT API Documentation or E-VAT API Documentation or VCIS/VSDC API Documentation) describes the API specification for the integration of Taxpayer systems to the Commissioner-General's Electronic Invoicing Systems (E-VAT).\n\n<u><b>OVERVIEW</b></u>  \nThe following specific requirements are for the systems to communicate with E-VAT VCIS, the Certified Invoicing System to be used together with a Virtual Sales Data Controller (VSDC).\n\n[Data Flow Diagram](https://gra.evatgra.com/DataFlow.php)\n\n<u><b>AUTHENTICATION</b></u>  \nThis API requires an Authentication in the Request Header  \nExample: \"security_key\": \"1234567890987UIEGRTEIIIWOWPPWOOW\"\n\nThe security key is a static value that will be expected across all endpoints that data is sent, whenever a request is made.\n\n<u><b>DATA FORMAT</b></u>  \nE-VAT API Receives accepts payloads in any of the formats below:\n\n1. JSON\n    \n2. XML\n    \n\n<u><b>DEPLOYMENT TYPE</b></u>  \nTaxpayers are allowed to choose between the cloud deployment and the On-Prem deployment.  \nCloud Deployment is where GRA hosts the software that stamps your E-VAT invoices  \nOn-Prem Deployment is where the taxpayer provides a server, either within their network (preferably) or a dedicated private cloud server.  \nThe EVAT Team recommends for taxpayers that issue huge number of invoices within a day to opt for the On-Prem Deployment\n\n<u><b>ON-PREM DEPLOYMENT MINIMUM HARDWARE SPECIFICATION</b></u>\n\n- HDD: 500GB\n    \n- RAM: 8GB\n    \n- OS: Windows Server 2019 + / Windows 10 +\n    \n\n**LEVY MAPPING**\n\n- levyAmountA : NHIL 2.5 %\n    \n- levyAmountB: GETFL 2.5 %\n    \n- levyAmountC : COVID 1% (Applies to invoice dates before 1st January 2026)\n    \n- levyAmountD : CST 5%\n    \n- levyAmountE : TOURISM LEVY 1%\n    \n\n**EXCEL TEMPLATE OF TAX CALCULATION**  \n[https://docs.google.com/spreadsheets/d/1PHctBuGkW6KG_O4id_1PYLPnirfC6ouo/edit?invite=CP_MgMsB&amp;gid=262008697#gid=262008697](https://docs.google.com/spreadsheets/d/1PHctBuGkW6KG_O4id_1PYLPnirfC6ouo/edit?invite=CP_MgMsB&gid=262008697#gid=262008697)\n\n<u><b>STAGING ENVIRONMENT SECURITY KEYS</b></u>  \n{  \n\"security_key\": \" Z60gftKe9sei3xOZhvvDa0StkVILKR3j5MBM9ygi1zg=\",  \n\"reference\": \"CXX000000YY-001\",  \n}  \n{  \n\"security_key\": \"xbPeYDaPFG7bqnNO7WThWRDrBhKggz+ls/6rV38zyA1iqe7dPg8Pc2EElmrUq+2v\",  \n\"reference\": \"CXX000000YY-006\",  \n}  \n{  \n\"security_key\": \"49BvCVhgjRxx3kbE4hiCLZrq8VKjKpKt0zfW1pJg9wClpcXOttM6cV83UtitMAx3\",  \n\"reference\": \"CXX000000YY-007\",  \n}  \n{  \n\"security_key\": \"Yqu34/kLbewAY1NCH3lKjUEaZFFNtoxpiLzKGI8JrcdrUmxO9ud8dZO2Nx/mQPAE\",  \n\"reference\": \"CXX000000YY-008\",\n\n}\n\n**SAMPLE INVOICE**\n\nSample Invoice - ERP/A4:\n\n<img src=\"https://content.pstmn.io/2c4e828a-22ec-411e-8ee0-ab34849d1f86/U2FtcGxlIGludm9pY2UucG5n\" width=\"599\" height=\"789\">\n\nSample Invoice - POS:\n\n<img src=\"https://content.pstmn.io/36f82f30-62d8-4de4-88bc-019379a496e5/cG9zIHNhbXBsZS5wbmc=\" width=\"344\" height=\"1211\">\n\n**CURRENCIES SUPPORTED**\n\n[https://docs.google.com/spreadsheets/d/1geCW7gk-LvHiAXQsigNDObDsFYCXS-pSGGBKQx78JkI/edit?usp=sharing](https://docs.google.com/spreadsheets/d/1geCW7gk-LvHiAXQsigNDObDsFYCXS-pSGGBKQx78JkI/edit?usp=sharing)\n\n**TAG DESCRIPTION**\n\n| TAG NAME | TAG VALUE EXAMPLE | TAG DESCRIPTION | LENGTH AND TYPE | MANDATORY |\n| --- | --- | --- | --- | --- |\n| \"currency\" | \"GHS\" | Currency: GHS, USD, EUR or GBP | VARCHAR(20) | YES |\n| \"exchangeRate\" | 1.00 | Current exchange rate: default 1 for GHS | NUMERIC | YES |\n| \"invoiceNumber\" | \"INV_26_001\" | Software unique transaction identifier | VARCHAR(100) | YES |\n| \"totalLevy\" | 30.00 | Total levy amount (summation of levies a, b, c, d, e) | NUMERIC | YES |\n| \"userName\" | \"happy\" | User name | VARCHAR(100) | YES |\n| \"flag\" | \"INVOICE\" | This determines the type of transaction about to be sent. Examples: \"INVOICE\", \"PURCHASE\", \"REFUND\" (full cancellation), \"PARTIAL_REFUND\" (partial cancellation), \"PURCHASE_RETURN\", \"REFUND_CANCELLATION\". This is a case sensitive field. | VARCHAR(20) | YES |\n| \"calculationType\" | \"INCLUSIVE\" | \"INCLUSIVE\" or \"EXCLUSIVE\". Where unit price has tax embedded (INCLUSIVE) or tax not included (EXCLUSIVE). Case sensitive. | VARCHAR(20) | YES |\n| \"totalVat\" | 13.04 | Total VAT of the invoice: Summation of 15% value for all taxable items | NUMERIC | YES |\n| \"transactionDate\" | \"2026-02-28\" | Invoice date (posted date is the one used) | VARCHAR(50) | YES |\n| \"totalAmount\" | 100.0 | Total amount on the invoice. Strictly the summation of unit price × quantity regardless of calculation type. | NUMERIC | YES |\n| \"voucherAmount\" | 0.0 | Voucher amount | NUMERIC | NO |\n| \"totalExciseAmount\" | 600 | Total excise amount on the invoice | NUMERIC | YES if excise duty is applicable |\n| \"businessPartnerName\" | \"James Kofi\" | Customer / Supplier name | VARCHAR(100) | YES |\n| \"businessPartnerTin\" | \"C00000009055\" | Client's TIN or Ghana card number | VARCHAR(15) | YES |\n| \"saleType\" | \"NORMAL\" | \"NORMAL\" for general case, \"EXPORT\" for export invoice. Case sensitive. | VARCHAR(20) | YES |\n| \"discountType\" | \"GENERAL\" | \"SELECTIVE\" (discount on total amount, taxable) or \"GENERAL\" (discount per line, tax exempt). Case sensitive. | VARCHAR(300) | NO |\n| \"discountAmount\" | 0.0 | Total discounted amount on invoice | NUMERIC | NO |\n| \"groupReferenceId\" | \"\" | Reference ID to group invoices together under one main identifier | VARCHAR(50) | NO |\n| \"reference\" | \"RF_INV_26_001\" | Refund ID for full or partial refunds. Identifies the refund transaction. | VARCHAR(50) | YES – For Refunds and Returns Only |\n| \"itemCode\" | \"TXC005918138\" | Item code: unique value identifying an item | VARCHAR(50) | YES |\n| \"itemCategory\" | \"\" | \"\" (standard 20%), \"CST\" (5% comms tax), \"TRSM\" (1% tourism), \"EXM\" (zero rated/exempt), \"RNT\" (rent), \"EXC_PLASTIC\" (plastic with excise duty). Case sensitive. | VARCHAR(50) | YES |\n| \"expireDate\" | \"\" | Expiry date of an item if applicable | VARCHAR(45) | NO |\n| \"description\" | \"Bowl\" | Name of the item | VARCHAR(100) | YES |\n| \"quantity\" | 10.0 | Quantity of the item | NUMERIC | YES |\n| \"levyAmountA\" | 2.05 | Levy amount on NHIL (2.5%) | NUMERIC | YES |\n| \"levyAmountB\" | 2.05 | Levy amount on GETFUND (2.5%) | NUMERIC | YES |\n| \"levyAmountC\" | 0.8 | Levy amount on COVID (1%) – Only for invoices created before 1st January 2026 | NUMERIC | YES |\n| \"levyAmountD\" | 0.0 | Levy amount on CST (5%) | NUMERIC | YES |\n| \"levyAmountE\" | 0.0 | Levy amount on tourism (1%) | NUMERIC | YES |\n| \"discountAmount\" | 0.0 | Discount amount on item | NUMERIC | NO |\n| \"exciseAmount\" | 10 | Excise duty amount on item | NUMERIC | (Not specified) |\n| \"batchCode\" | \"5MAKD1\" | Batch number if applicable | VARCHAR(100) | NO |\n| \"unitPrice\" | 10.0 | Unit selling price of item (inclusive or exclusive of tax) | NUMERIC | YES |\n\n**SUCCESS RESPONSE DESCRIPTION:**\n\n| FIELD | LABEL | DESCRIPTION |\n| --- | --- | --- |\n| \"distributor_tin\" | TIN | TIN of Taxpayer issuing the invoice |\n| \"num\" | Invoice Number | ERP/PoS Invoice Number as sent to the VSDC |\n| \"ysdcid\" | SDC ID | The unique identifier of the SDC (Sales Data Controller) issuing the E-VAT Signature |\n| \"ysdcrecnum\" | Receipt Number | The Receipt Number issued by the SDC |\n| \"ysdcintdata\" | Internal Data | References the Internal Data of the Invoice |\n| \"ysdcregsig\" | Signature | Invoice Signature |\n| \"ysdcmrc\" | MRC | Machine Registration Code |\n| \"ysdcmrctime\" | MRC Date & Time | Date/Time invoice is received at the backend |\n| \"ysdctime\" | Date & Time | Date/Time invoice is stamped |\n| \"flag\" | (empty) | Type of Invoice |\n| \"ysdcitems\" | Line-Item Count | Number of Line-Items on the invoice |\n| \"qr_code\" | (empty) | URL link to be converted to QR Code Image |\n| \"status\" | (empty) | Status of invoice request |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"29809098","team":5575878,"collectionId":"9154d680-6787-40f7-9627-f625e0b9a803","publishedId":"2sBXVeGCzK","public":true,"publicUrl":"https://documenter-api.postman.tech/view/29809098/2sBXVeGCzK","privateUrl":"https://go.postman.co/documentation/29809098-9154d680-6787-40f7-9627-f625e0b9a803","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.11.6","publishDate":"2026-01-08T17:42:11.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/84a5e4cf9bf8ccc7960f2ca33d43b0a747f998bb8b0cf652d5176e3683d3647c","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sBXVeGCzK"}