Comprehensive Iranian Tax Authority (Moadian) E-Invoicing Guide via Keysun TSP
The enactment of the Law of POS Terminals and Taxpayer System (قانون پایانههای فروشگاهی و سامانه مودیان) represents the most significant tax compliance transformation in Iran in decades. All registered businesses, corporations, and e-commerce stores are legally mandated to transmit standardized electronic sales invoices with a 22-digit unique Tax ID (TaxID) to the National Tax Administration (سازمان امور مالیاتی کشور - INTA / tp.tax.gov.ir).
Direct integration with INTA's central servers presents severe technical hurdles (mandatory RSA private keys, CSR generation, asymmetric JWS signing, AES packet encryption, and frequent gateway timeouts). To solve this, the Tax Authority officially certified Type-1 Tax Service Providers (TSP).
Keysun Data Processing (keysuntsp.com) is Iran's premier certified Type-1 TSP. The Webito moadian-kaysan plugin automates 100% of fiscal invoice generation, Verhoeff checksum calculation, and e-invoice transmission with zero hardware tokens required on your server.
1. Direct INTA Connection vs. Keysun TSP in Webito
| Requirement / Challenge | Direct Tax Authority Connection | Webito via Keysun TSP |
|---|---|---|
| Hardware Token / RSA Private Key | Mandatory on server (High Risk) | Not Required (Keysun Digital Seal) |
| 22-Digit TaxID with Verhoeff Checksum | Complex manual math by developer | 100% Automated by Webito |
| Tax Authority Server Downtime Handling | Frequent 504 errors & failed invoices | Automated Retry Queuing by Keysun |
| Error Diagnosis & Rejection Feedback | Opaque numerical error codes | Clear Persian / English Diagnostics |
| Technical Support Hotline | No dedicated INTA support line | Corporate Keysun Support (021-91009610) |
2. Anatomy of the 22-Digit Tax ID (TaxID)
Webito implements the exact INTA mathematical specification in moadian-tax-id.util.ts:
$$\text{TaxID (22 chars)} = \underbrace{\text{A12BC3}}{\text{Fiscal Memory (6)}} + \underbrace{\text{20716}}{\text{Julian Day (5)}} + \underbrace{\text{0000000101}}{\text{Invoice Serial (10)}} + \underbrace{\text{5}}{\text{Verhoeff Check Digit (1)}}$$
- Fiscal Memory ID (6 characters): Unique terminal identifier issued in your
my.tax.gov.irportal. - Julian Day Number (5 digits): Elapsed days since epoch (1970-01-01) corresponding to invoice issuance date.
- Internal Invoice Serial (10 digits): Sequential decimal number unique per fiscal memory terminal.
- Verhoeff Checksum (1 digit): Computed using dihedral group $D_5$ permutations preventing typographical fraud.
3. Type-1 (B2B) vs. Type-2 (B2C) Invoice Patterns
- Pattern 1 (B2B Commercial Sales): For wholesale and corporate sales. Requires buyer Economic Code (
tinb), National ID (bid), and 10-digit postal code (bpc). Buyers can claim input VAT tax credits. - Pattern 2 (B2C Consumer Retail): Standard consumer e-commerce sales. Does not require buyer economic codes or postal validation.
4. Configuration Parameters
| Parameter in Webito | Description | Example |
|---|---|---|
| Kaysan API Key | Dedicated REST API Key from keysuntsp.com dashboard | kys_live_apikey_9988 |
| Fiscal Memory ID | 6-character terminal memory code from my.tax.gov.ir | A12BC3 |
| Seller Economic Code | Merchant 11 or 14-digit National Economic/Tax ID | 14001234567 |
| Default Pattern | Pattern 1 (B2B) or Pattern 2 (B2C Retail) | 2 |
| Default Commodity Code | 13-digit standard code from stuffid.tax.gov.ir | 2720000114913 |
| Custom API URL | Optional dedicated enterprise endpoint override | https://api.keysuntsp.com/v1 |
5. Troubleshooting Tax Authority Rejections
| Rejection Reason | Cause | Resolution in Webito |
|---|---|---|
Invalid Commodity Code | 13-digit code not registered in stuffid.tax.gov.ir | Use general registered code 2720000114913. |
Buyer Postal Code Mismatch | Buyer postal code does not match post database | Correct buyer address in Webito order details. |
VAT Calculation Discrepancy | Rounding mismatch in 10% VAT calculation | Webito enforces exact integer Rial rounding. |
Duplicate Tax ID | Invoice with same serial already transmitted | Webito automatically increments serial sequence. |