Validates european vat numbers. Standalone or as a ActiveModel validator.
Pull request Compare This branch is 275 commits behind yolk:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Validates european vat numbers. Standalone or as a ActiveModel validator.


  • Simple syntax verification
  • Lookup via the VIES web service
  • (Optional) ActiveModel/Rails3 integration
  • Works standalone without ActiveModel
  • I18n locales for country specific error messages

valvat is tested and works with ruby 1.8.7/1.9.2 and ActiveModel 3.0.


gem install valvat

Basic Usage

To verify the syntax of a vat number:"DE345789003").valid?
=> true or false

To check if the given vat number exists via the VIES web service:"DE345789003").exists?
=> true or false or nil

Keep in mind that the VIES web service might be offline at some time for some countries. If this happens Valvat::Lookup.validate returns nil.

Visit for more accurate information at what time the service for a specific country will be down.

It is also possible to bypass initializing a Valvat instance and check the syntax of a var number string directly with:

=> true or false

Or to lookup a vat number string directly via VIES web service:

=> true or false or nil

ActiveModel/Rails3 Usage


When the valvat gem is required and ActiveModel is already loaded, everything will work fine out of the box. If your load order differs just add

require 'valvat/active_model'

after ActiveModel has been loaded.

Simple syntax validation

To validate the attribute vat_number add this to your model:

class MyModel < ActiveRecord::Base
  validates :vat_number, :valvat => true

Additional lookup validation

To additionally perform a lookup via VIES:

validates :vat_number, :valvat => {:lookup => true}

By default this will validate to true if the VIES web service is down. To fail in this case simply add the :fail_if_down option:

validates :vat_number, :valvat => {:lookup => :fail_if_down}

Additional ISO country code validation

If you want the vat number’s (ISO) country to match another country attribute, use the match_country option:

validates :vat_number, :valvat => {:match_country => :country}

where it is supposed that your model has a method named country which returns the country ISO code you want to match.

Allow blank

By default blank vat numbers validate to false. To change this add the :allow_blank option:

validates :vat_number, :valvat => {:allow_blank => true}

Allow vat numbers outside of europe

To allow vat numbers from outside of europe, add something like this to your model (country_code should return a upcase ISO country code):

class MyModel < ActiveRecord::Base
  validates :vat_number, :valvat => true, :if => :eu?
  def eu?


To split a vat number into the country code and the remaining chars:

=> ["AT", "U345789003"]

=> ["AT", "U345789003"]

Both methods always return an array. If it can not detect the country or the given country is located outside of europe it returns [nil, nil]. Please note that this does not strictly return the ISO country code: for greek vat numbers this returns the ISO language code 'EL' instead of the ISO country code 'GR'.

To extract the ISO country code of a given vat number:"EL7345789003").iso_country_code
=> "GR"

To extract the vat country code (first two chars in every european vat number):"EL7345789003").vat_country_code
=> "EL"

To normalize a vat number:

=> "ATU345789003"

This basically just removes trailing spaces and ensures all chars are uppercase.



Copyright (c) 2011 Yolk Sebastian Munz & Julia Soergel GbR

Beyond that, the implementation is licensed under the MIT License.