Aakvatech Limited - Setting Up TotalVFD as Your VFD Provider in ERPNext

A step-by-step guide to configuring TotalVFD for fiscal receipt submission in ERPNext using the VFD Providers app.

February 25, 2026 · 5 min read

Setting Up TotalVFD as Your VFD Provider in ERPNext

Tanzania VFD Compliance · ERPNext / VFD Providers App A step-by-step guide to configuring TotalVFD for fiscal receipt submission in ERPNext using the VFD Providers app.

Introduction

In Tanzania, businesses are required to use a Virtual Fiscal Device (VFD) to submit fiscal receipts to the Tanzania Revenue Authority (TRA). ERPNext supports multiple VFD providers through the VFD Providers app — an open-source app maintained by Aakvatech Limited that provides a pluggable VFD Provider DocType for managing provider configurations.

TotalVFD is a Tanzanian VFD middleware platform with a straightforward REST API for fiscal sales invoice submission. TotalVFD uses a pre-issued bearer token tied directly to your TIN, VRN, and device serial — there is no login or token refresh flow required, making the integration simple and reliable.

Prerequisites - The VFD Providers app installed on your ERPNext instance - A TotalVFD account with a bearer token and active business identifier issued by TotalVFD - Your TRA-registered TIN, VRN, and device serial number - System Manager access to your ERPNext site

About the VFD Providers App

The VFD Providers app is an open-source Frappe/ERPNext application developed and maintained by Aakvatech Limited. It provides the VFD Provider DocType which stores the base URL and API endpoint paths for each VFD middleware provider, allowing ERPNext to dynamically construct API requests without any code changes when switching providers.

→ https://github.com/Aakvatech-Limited/vfd_providers

Installation

cd /home/frappe/frappe-bench
bench get-app https://github.com/Aakvatech-Limited/vfd_providers
bench --site your-site.example.com install-app vfd_providers
bench migrate

TotalVFD API Endpoints

TotalVFD uses a REST API hosted at https://api.totalvfd.co.tz. The VFD Providers app uses one endpoint:

Key	Endpoint Path	Purpose
`sales`	`/sales`	Submit a fiscal sales invoice to TRA

Authentication

TotalVFD uses a static bearer token issued when your account is activated. This token is provided directly by TotalVFD and stored once in your Total VFD Setting document. There is no login step or token expiry to manage — the token remains valid for the lifetime of your TotalVFD account.

All API requests include the bearer token in the Authorization header alongside an X-Active-Business identifier that scopes the request to your registered business entity.

Step-by-Step Setup

Step 1 — Create the VFD Provider Record

In ERPNext, navigate to VFD Provider (search for it in the search bar). Create a new document with the following values:

Field	Value
VFD Provider (name)	`TotalVFD`
Base URL	`https://api.totalvfd.co.tz`
VFD Provider Settings	`Total VFD Setting`

Step 2 — Add the API Endpoint Attribute

In the Attributes child table, add the single endpoint row:

Key	Value
`sales`	`/sales`

Step 3 — Configure Total VFD Setting

Navigate to Total VFD Setting and fill in your TotalVFD account details:

Field	Description
Company	Your ERPNext company name
Serial ID	Your TRA-registered VFD device serial (e.g. `10UK123212`)
TIN	Your TRA Tax Identification Number (e.g. `100321660`)
VRN	Your TRA VAT Registration Number (e.g. `10012324F`)
Bearer Token	The static API token issued by TotalVFD
X Active Business	The active business identifier issued by TotalVFD
Is VAT Grouped	Tick if your invoices report VAT as a grouped total
Enable VFD Preview	Tick to preview receipts before submission (optional)

⚠️ Security Note The Bearer Token and X Active Business fields contain sensitive credentials issued by TotalVFD. Keep these private — do not share your Total VFD Setting document export publicly. Store them only in your ERPNext instance.

Step 4 — Set TotalVFD as the Active Provider

Go to VFD Settings and set the VFD Provider field to TotalVFD. Save the document.

Step 5 — Test with a Sales Invoice

Create or open a test Sales Invoice, enable VFD on it, and submit. The app will call POST /sales with the fiscal payload and store the TRA receipt number and verification details on the invoice upon success.

Provider JSON Reference

If you are setting this up via a fixture file or data migration, here is the complete VFD Provider JSON record for TotalVFD:

{
  "doctype": "VFD Provider",
  "vfd_provider": "TotalVFD",
  "base_url": "https://api.totalvfd.co.tz",
  "vfd_provider_settings": "Total VFD Setting",
  "attributes": [
    {
      "key": "sales",
      "value": "/sales"
    }
  ]
}

Using as a Fixture Save this JSON as vfd_provider/TotalVFD.json inside your custom app's fixtures folder, then run bench migrate to automatically import it on new site deployments. Credentials in Total VFD Setting must still be configured manually per site.

API Endpoint Explained

`POST /sales`

Submits a fiscal sales invoice payload to TRA via the TotalVFD API. Requires a valid bearer token in the Authorization header and the X-Active-Business identifier. Called automatically on Sales Invoice submission when VFD is enabled and TotalVFD is the active provider.

Key Differences from Other Providers

TotalVFD has the simplest integration profile of the supported providers — a single endpoint with no authentication flow to manage:

Feature	VFDPlus	SimplifyVFD	TotalVFD
Authentication	Static API key / token	JWT login + refresh flow	Static bearer token
Endpoints	4	3	1
Token management	Not required	Automatic via `refresh`	Not required
VAT grouping option	Available	Available	Available
Base URL	`https://app.vfdplus.co.tz`	`https://simplify.co.tz/partner/v1`	`https://api.totalvfd.co.tz`

Troubleshooting

Invoice submission returns 401 Unauthorized

Your bearer token or X Active Business value is incorrect or has been revoked. Verify both values in Total VFD Setting match exactly what was issued by TotalVFD. Contact TotalVFD support if you need your credentials reissued.

TRA rejects the invoice with a TIN/VRN mismatch

Check that the TIN, VRN, and Serial ID fields in Total VFD Setting exactly match your TRA registration. Even a leading zero difference will cause rejections.

VAT amounts look incorrect on submitted receipts

If your invoice reports VAT as a single grouped line rather than per-item, ensure Is VAT Grouped is ticked in Total VFD Setting. If it is already ticked and amounts are still wrong, review how tax templates are configured on your items.

Connection errors / timeout

Confirm your ERPNext server has outbound internet access to api.totalvfd.co.tz on port 443:

curl -I https://api.totalvfd.co.tz/sales

⚠️ Test in Sandbox First Confirm with TotalVFD whether a sandbox/test environment is available. Always validate your integration in a non-production environment before submitting live receipts to TRA.

Contributing

The VFD Providers app is open source and contributions are welcome. If you add support for a new VFD provider or improve existing functionality, please submit a pull request: