VFD Provider App - Custom Fields Documentation

Table of Contents

1. Overview
2. What is VFD (Virtual Fiscal Device)?
3. Custom Fields by Doctype
4. Implementation Guide
5. Technical Reference

Overview

The VFD Provider App is a Frappe/ERPNext application developed by Aakvatech Limited that enables businesses in Tanzania to comply with the Tanzania Revenue Authority (TRA) Virtual Fiscal Device (VFD) requirements. This app extends existing ERPNext doctypes with VFD-specific fields and functionality to ensure proper tax compliance and electronic receipt generation.

What is VFD (Virtual Fiscal Device)?

Purpose and Legal Requirement

A Virtual Fiscal Device (VFD) is a software-based solution mandated by the Tanzania Revenue Authority (TRA) for businesses to:

• Generate electronic fiscal receipts for all sales transactions
• Ensure proper VAT collection and reporting
• Maintain compliance with Tanzanian tax regulations
• Provide real-time transaction reporting to TRA

How VFD Works

1. Transaction Processing: When a sale is made, the system generates transaction data
2. VFD Submission: Transaction details are sent to TRA's VFD servers
3. Receipt Generation: TRA returns a fiscal receipt number and verification URL
4. Customer Receipt: Customers receive receipts with TRA verification codes

Business Benefits

• Legal Compliance: Meets TRA requirements for electronic receipts
• Tax Accuracy: Ensures correct VAT calculation and reporting
• Audit Trail: Maintains complete transaction history for tax audits
• Customer Trust: Provides verifiable receipts with TRA validation

Custom Fields by Doctype

1. Customer Doctype

The VFD Provider app adds customer identification fields required for VFD compliance:

VFD Details Section

• Field: vfd_details
• Type: Section Break
• Purpose: Groups VFD-related customer information
• Position: After "Tax Withholding Category"

VFD Customer ID

• Field: vfd_cust_id
• Type: Data (Text)
• Purpose: Stores the customer's identification number for VFD receipts
• Required: Yes
• Usage: This ID appears on all VFD receipts for the customer

VFD Customer ID Type

• Field: vfd_cust_id_type
• Type: Select (Dropdown)
• Purpose: Specifies the type of identification document
• Required: Yes
• Options:
  • 1- TIN (Tax Identification Number)
  • 2- Passport
  • 3- Driving License
  • 4- Voter ID
  • 5- Aadhaar
  • 6- Other

Why These Fields Matter: TRA requires customer identification on all fiscal receipts. The ID type and number ensure proper customer tracking and compliance with tax regulations.

2. Sales Invoice Doctype

The Sales Invoice receives the most extensive VFD customizations, covering the entire VFD generation and tracking process:

VFD Generation Control

Generate VFD Button

• Field: generate_vfd
• Type: Button
• Purpose: Manually triggers VFD receipt generation
• Visibility: Only shown when:
  • Invoice is submitted (docstatus = 1)
  • Not marked as non-VFD invoice
  • VFD status is not "Success"
  • Not a return invoice
• Position: After "Due Date"

VFD Details Section

• Field: vfd_details
• Type: Section Break (Collapsible)
• Purpose: Groups all VFD-related information
• Visibility: Hidden from Healthcare Receptionists
• Position: After "Auth OTP"

VFD Transaction Information

VFD Date

• Field: vfd_date
• Type: Date
• Purpose: Records when the VFD receipt was generated
• Read Only: Yes (automatically set by system)

VFD Time

• Field: vfd_time
• Type: Time
• Purpose: Records the exact time of VFD generation
• Read Only: Yes (automatically set by system)

VFD Posting Info

• Field: vfd_posting_info
• Type: Link to "VFD Provider Posting"
• Purpose: Links to detailed VFD submission record
• Read Only: Yes

VFD Verification URL

• Field: vfd_verification_url
• Type: Data (Text, max 1000 characters)
• Purpose: Stores TRA-provided URL for receipt verification
• Read Only: Yes
• Usage: Customers can use this URL to verify receipt authenticity

VFD Control Numbers

VFD DC (Document Control)

• Field: vfd_dc
• Type: Integer
• Purpose: TRA-assigned document control number
• Read Only: Yes

VFD GC (Global Control)

• Field: vfd_gc
• Type: Integer
• Purpose: TRA-assigned global control number
• Read Only: Yes

VFD Status and Control

VFD Status

• Field: vfd_status
• Type: Select
• Purpose: Tracks VFD submission status
• Default: "Not Sent"
• Options:
  • Not Sent: Invoice not yet submitted to VFD
  • Pending: Submission in progress
  • Failed: Submission failed (requires retry)
  • Success: Successfully submitted to TRA
• List View: Visible in invoice lists for quick status checking
• Filter: Available as standard filter

Is Not VFD Invoice

• Field: is_not_vfd_invoice
• Type: Checkbox
• Purpose: Excludes invoice from VFD processing
• Usage: For internal transactions or non-taxable sales

Is Auto Generate VFD

• Field: is_auto_generate_vfd
• Type: Checkbox
• Purpose: Enables automatic VFD generation on invoice submission
• Default: Based on company settings

Customer Information (Fetched)

VFD Customer ID Type (Fetched)

• Field: vfd_cust_id_type
• Type: Data
• Purpose: Automatically fetched from Customer master
• Source: customer.vfd_cust_id_type

VFD Customer ID (Fetched)

• Field: vfd_cust_id
• Type: Data
• Purpose: Automatically fetched from Customer master
• Source: customer.vfd_cust_id

VFD Receipt Numbers

VFD RCTNUM

• Field: vfd_rctnum
• Type: Data
• Purpose: TRA-assigned receipt number
• Read Only: Yes

VFD RCTVNUM

• Field: vfd_rctvnum
• Type: Data
• Purpose: TRA-assigned receipt verification number
• Read Only: Yes

VFD SERIAL

• Field: vfd_serial
• Type: Data
• Purpose: VFD device serial number
• Read Only: Yes

Why These Fields Matter: Sales invoices must be submitted to TRA for VFD compliance. These fields track the entire process from submission to receipt generation, ensuring complete audit trails and legal compliance.

3. Item Tax Template Doctype

VFD Tax Code

• Field: vfd_taxcode
• Type: Select
• Purpose: Maps ERPNext tax templates to TRA tax categories
• Position: After "Taxes" table
• Options:
  • 1- Standard Rate (18%): Standard VAT rate
  • 2- Special Rate: Special VAT rates
  • 3- Zero rated: Zero-rated items
  • 4- Special Relief: Tax relief items
  • 5- Exempt: Tax-exempt items

Why This Field Matters: TRA requires specific tax codes for different item categories. This mapping ensures correct tax reporting and compliance with Tanzanian tax regulations.

4. Mode of Payment Doctype

VFD Payment Type

• Field: vfd_pmttype
• Type: Select
• Purpose: Maps payment methods to VFD payment types
• Position: After "Accounts" table
• Options:
  • CASH: Cash payments
  • CHEQUE: Check payments
  • CCARD: Credit card payments
  • EMONEY: Electronic money/mobile payments
  • INVOICE: Credit/invoice payments

Why This Field Matters: VFD receipts must specify payment methods using TRA-defined codes. This ensures accurate payment reporting and compliance.

Implementation Guide

Initial Setup

1. Install VFD Provider App

# Install the app
bench get-app vfd_providers
bench install-app vfd_providers --site your-site-name

2. Configure VFD Provider

1. Go to VFD Provider doctype
2. Create a new VFD Provider record
3. Set provider details (VFDPlus, TotalVFD, etc.)
4. Configure API endpoints and settings

3. Company VFD Configuration

1. Go to Company VFD Provider doctype
2. Link your company to the VFD provider
3. Configure company-specific VFD settings

4. Configure Tax Templates

1. Open Item Tax Template records
2. Set appropriate VFD Tax Code for each template
3. Ensure all items have proper tax templates assigned

5. Configure Payment Methods

1. Open Mode of Payment records
2. Set appropriate VFD Payment Type for each method
3. Ensure all payment methods are properly mapped

Daily Usage Workflow

Customer Setup

1. Create/Update Customers:
   • Enter VFD Customer ID (TIN, Passport, etc.)
   • Select VFD Customer ID Type
   • Save customer record

Invoice Processing

1. Create Sales Invoice:

   • Add items with proper tax templates
   • Select customer with VFD details
   • Choose payment method with VFD mapping

2. VFD Generation:

   • Automatic: Enable "Is Auto Generate VFD" for automatic submission
   • Manual: Click "Generate VFD" button after submission

3. Monitor Status:

   • Check VFD Status field
   • Review VFD Verification URL for customer
   • Verify receipt numbers are populated

Troubleshooting

• Failed Status: Check VFD Provider settings and retry
• Missing Customer ID: Update customer master data
• Tax Code Errors: Verify Item Tax Template configurations
• Payment Type Issues: Check Mode of Payment VFD mappings

Best Practices

Data Management

• Customer IDs: Always collect proper identification from customers
• Tax Templates: Maintain accurate tax code mappings
• Payment Methods: Ensure all payment types are VFD-compliant

Compliance

• Regular Monitoring: Check VFD status on all invoices
• Backup Procedures: Maintain records of all VFD submissions
• Error Handling: Address failed submissions promptly

Performance

• Batch Processing: Use auto-generation for high-volume operations
• Network Reliability: Ensure stable internet for VFD submissions
• System Monitoring: Track VFD Provider Posting records for issues

Technical Reference

File Locations

• Custom Fields Patch: apps/vfd_providers/vfd_providers/patches/custom_fields/vfd_providers_updated_custom_fields.py
• Hooks Configuration: apps/vfd_providers/vfd_providers/hooks.py
• VFD Logic: apps/vfd_providers/vfd_providers/utils/

Related Doctypes

• VFD Provider: Main provider configuration
• VFD Provider Posting: Transaction submission records
• Total VFD Setting: Provider-specific settings
• Company VFD Provider: Company-provider mapping

Integration Points

• Sales Invoice Events: Automatic VFD generation on submission
• Customer Validation: ID information cleanup and validation
• Tax Calculation: Integration with ERPNext tax system
• Payment Processing: VFD payment type mapping

This documentation provides a complete reference for understanding and implementing the VFD Provider app's custom fields in ERPNext, ensuring proper VFD compliance for Tanzanian businesses.