Giter VIP home page Giter VIP logo

tax-ids's Introduction

Tax Ids

This crate offers a solution for validating tax IDs (VAT/GST) for businesses operating within the European Union, the United Kingdom, Switzerland, and Norway.

Currently, the library provides the following functionalities:

  • Validates the syntax of a tax ID against its type-specific regex pattern.
  • Verifies the tax ID in the relevant government database (based on the tax ID type).

The library has been inspired by the valvat library for Ruby.

Available features / tax id types

Feature Description Default
eu_vat European Union VAT
gb_vat United Kingdom VAT
ch_vat Switzerland VAT
no_vat Norway VAT

More info at Tax Id Types.

Installation

With default feature eu_vat:

[dependencies]
tax_ids = "0.1.0"

With eu_vat and gb_vat features enabled:

[dependencies]
tax_ids = { version = "0.1.0", features = ["eu_vat", "gb_vat"] }

Usage

use tax_ids::TaxId;
use tax_ids::VerificationStatus::{Verified, Unverified, Unavailable};
use tax_ids::UnavailableReason::{ServiceUnavailable, Timeout, Block, RateLimit};

fn main() {
  // Instantiate a new TaxId object. This can raise a ValidationError.
  let tax_id = match TaxId::new("SE556703748501") {
    Ok(tax_id) => tax_id,
    Err(e) => {
      println!("ValidationError: {}", e);
      return;
    }
  };

  assert_eq!(tax_id.value(), "SE556703748501");
  assert_eq!(tax_id.country_code(), "SE");
  assert_eq!(tax_id.tax_country_code(), "SE");
  assert_eq!(tax_id.local_value(), "556703748501");
  assert_eq!(tax_id.tax_id_type(), "eu_vat");

  // The country code is the 2-char ISO code of the country.
  // It's often the same as the tax country code, but not always.
  // For example, the country code for Greece is GR, but EL for the Greek VAT number.

  // The United Kingdom has a country code GB and tax country code GB.
  // However, due to Brexit, businesses in Northern Ireland
  // have a country code GB but use VAT number/tax country code XI when trading
  // with the EU.

  // Verification

  // Perform a verification request against the country's tax ID database.
  // This can raise a VerificationError.
  let verification = match tax_id.verify() {
    Ok(verification) => verification,
    Err(e) => {
      println!("VerificationError: {}", e);
      return;
    }
  };

  assert_eq!(verification.status(), &Verified);

  // VerificationStatus can take one out of three different statuses:
  // - Verified - The tax ID is legitimate.
  // - Unverified - The tax ID is not legitimate.
  // - Unavailable(UnavailableReason) - The verification couldn't be performed due to some reason.

  // These statuses are what you want to act upon.
  match verification.status() {
    Verified => {
      // Proceed with payment
    }
    Unverified => {
      // Ask the customer to provide a proper tax ID
    }
    Unavailable(reason) => {
      // Process payment and verify the tax ID later?
      
      match reason {
        ServiceUnavailable | Timeout => {},
        Block => {
          // Adapt to your IP / VAT being blocked
        }
        RateLimit => {
          // Consider how to avoid rate limiting
        }
      }
    }
  }

  // The full verification object:

  println!("{:?}", verification);

  // The data field is experimental and subject to change or removal.
  // It will contain different data depending on what tax ID type is being verified.
  // And what response the verification service provides.

  // Verification status: Verified
  // Verification {
  //    performed_at: 2024-05-15T14:38:31.388914+02:00,
  //    status: Verified,
  //    data: Object {
  //        "address": String("REGERINGSGATAN 19 \n111 53 STOCKHOLM"),
  //        "countryCode": String("SE"),
  //        "name": String("Spotify AB"),
  //        "requestDate": String("2024-05-15+02:00"),
  //        "valid": String("true"),
  //        "vatNumber": String("556703748501"
  //    )}
  // }
}

Tax Id Types

Tax Id Type Authority Manual lookup Documentation
eu_vat VIES 🔍 📖 + Availability
gb_vat HMRC 🔍 📖
ch_vat BFS 🔍 📖
no_vat Brønnøysundregistrene 🔍 📖

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

tax-ids's People

Contributors

mollemoll avatar

Stargazers

 avatar  avatar

Watchers

 avatar  avatar

tax-ids's Issues

feat: CH VATs

Need a validator and verifier to enable verification of CH VATs

CH VAT Syntax

CH VATs can take different formatting variations. They start with CHE, followed by 9 digits and an optional suffix describing the regional part of Switzerland (MWST, IVA or TVA).

Format examples:

CHE123456789
CHE123456789 MWST
CHE-123.456.789
CHE-123.456.789 MWST

Stripe
Alavara

BFS Lookup:

Does not accept CHE123456789MWST (without a whitespace before MWST)
Errors
According to Google Translate and the [Spécifications Webservice Interface 5.0 PDF](Spécifications Webservice
Interface 5.0) the ValidateVatNumber operation can only return two errors:

  • Data_validation_failed
  • Request_limit_exceeded

Sources

Lookup:
BFS UIDs
BFS SOAP API

Checksum details (weight and mod):
Details on checksum
PDF with checksum weights

feat: checksums

Add checksum control for tax ids that support it to avoid unnecessary calls to already strained APIs.

feat: GB VATs

Need a verifier for HMRC to enable verification of GBVats

feat: caching

Look into whether it could be worth adding caching

feat: NO VAT

Need a validator and verifier to lookup the legitimacy of NO VATs

feat: VIES service faults

The VIES service can reply with several fault codes. Right now they all lead to VerificationStatus Unavailable. However, it would be nice to forward the VIES fault within the Unavailable status in case the user can act upon it.

Here are the codes.

#[derive(Debug)]
pub enum VIESFault {
    ServiceUnavailable,
    MemberStateUnavailable,
    InvalidRequester,
    Timeout,
    BlockedError,
    RateLimitError,
}

lazy_static! {
    pub static ref VIES_FAULT: HashMap<&'static str, VIESFault> = {
        let mut m = HashMap::new();
        m.insert("SERVICE_UNAVAILABLE", VIESFault::ServiceUnavailable);
        m.insert("MS_UNAVAILABLE", VIESFault::MemberStateUnavailable);
        m.insert("INVALID_REQUESTER_INFO", VIESFault::InvalidRequester);
        m.insert("TIMEOUT", VIESFault::Timeout);
        m.insert("VAT_BLOCKED", VIESFault::BlockedError);
        m.insert("IP_BLOCKED", VIESFault::BlockedError);
        m.insert("GLOBAL_MAX_CONCURRENT_REQ", VIESFault::RateLimitError);
        m.insert("GLOBAL_MAX_CONCURRENT_REQ_TIME", VIESFault::RateLimitError);
        m.insert("MS_MAX_CONCURRENT_REQ", VIESFault::RateLimitError);
        m.insert("MS_MAX_CONCURRENT_REQ_TIME", VIESFault::RateLimitError);
        m
    };
}

feat: requester

Both VIES and HMRC accept incoming requests that include requester info, ie who's performing the lookup.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.