dragonbe/vies

EU VAT numbers validation using the VIES Service of the European Commission

Sunday, May 20, 2018
by DragonBe
Repository
7 Watchers
126 Stars
106,510 Installations

PHP
1 Dependents
0 Suggesters
20 Forks
1 Open issues
26 Versions
20 % Grown

The README.md

VIES

Component using the European Commission (EC) VAT Information Exchange System (VIES) to verify and validate VAT registration numbers in the EU, using PHP and Composer., _(*1)

The Vies class provides functionality to make a SOAP call to VIES and returns an object CheckVatResponse containing the following information:, _(*2)

Country code (string): a 2-character notation of the country code
VAT registration number (string): contains the complete registration number without the country code
Date of request (DateTime): the date when the request was made
Valid (boolean): flag indicating the registration number was valid (TRUE) or not (FALSE)
Name (string): registered company name (if provided by EC member state)
Address (string): registered company address (if provided by EC member state)

Stated on the European Commission website:, _(*3)

To make an intra-Community supply without charging VAT, you should ensure that the person to whom you are supplying the goods is a taxable person in another Member State, and that the goods in question have left, or will leave your Member State to another MS. VAT-number should also be in the invoice., _(*4)

More information at http://ec.europa.eu/taxation_customs/vies/faqvies.do#item16, _(*5)

, _(*6)

On May 25, 2018 the General Data Protection Regulation or GDPR becomes law within all 28 European Member States. Is this VIES service package going to be compliant with GDPR?, _(*7)

In short: yes., _(*8)

The longer answer is that this VIES package only interacts with the service for VAT ID verification provided by the European Commission. VAT validation is mandatory in European countries and therefor this service is allowed as lawfulness and legal basis. Please read more about this in European DPO-3816.1. This service does not store any data itself or collects more information than what's strictly required by law and provided by the EC VIES service., _(*9)

When you have implemented this service package in your own project, be sure that you're making sure you're just store the VAT ID, the timestamp of validation, the result of validation and optionally the given validation ID provided by the EC VIES service., _(*10)

Requirements

Minimum PHP version: 7.3
Recommended PHP version: 7.4
Extension: soap
Extension: pcntl
Extension: ctype

Please read the release notes for details., _(*11)

Installation

This project is on Packagist!, _(*12)

To install the latest stable version use composer require dragonbe/vies., _(*13)

To install specifically a version (e.g. 2.2.0), just add it to the command above, for example composer require dragonbe/vies:2.2.0, _(*14)

Usage

Here's a usage example you can immediately execute on the command line (or in cron, worker or whatever) as this will most likely be your most common usecase., _(*15)

1. Setting it up

<?php

use DragonBe\Vies\Vies;
use DragonBe\Vies\ViesException;
use DragonBe\Vies\ViesServiceException;

require_once dirname(__DIR__) . '/vendor/autoload.php';

$vies = new Vies();

2. See if the VIES service is alive

if (false === $vies->getHeartBeat()->isAlive()) {

    echo 'Service is not available at the moment, please try again later.' . PHP_EOL;
    exit(1);
}

If using a proxy, you can now use the following approach

$vies = new Vies();
$options = [
    'proxy_host' => '127.0.0.1',
    'proxy_port' => '8888',
];
$vies->setOptions($options);

$heartBeat = new \DragonBe\Vies\HeartBeat('tcp://' . $options['proxy_host'], $options['proxy_port']);
$vies->setHeartBeat($heartBeat);

$isAlive = $vies->getHeartBeat()->isAlive();

3. Validate VAT

Now that we know the service is alive, we can start validating VAT ID's, _(*16)

3.1. Simple usage

$vatResult = $vies->validateVat(
    'BE',           // Trader country code 
    '0203430576',   // Trader VAT ID
    'BE',           // Requester country code 
    '0811231190'    // Requester VAT ID
);

3.2. Advanced usage

$vatResult = $vies->validateVat(
    'BE',                 // Trader country code 
    '0203430576',         // Trader VAT ID
    'BE',                 // Requester country code 
    '0811231190'          // Requester VAT ID
    'B-Rail',             // Trader name
    'NV',                 // Trader company type
    'Frankrijkstraat 65', // Trader street address
    '1060',               // Trader postcode
    'Sint-Gillis'         // Trader city
);

3.3. Result methods

3.3.1. Is the VAT ID valid?

The most important functionality is to see if the VAT ID is valid, _(*17)

echo ($vatResult->isValid() ? 'Valid' : 'Not valid') . PHP_EOL;

// Result: Valid

3.3.2. Retrieve the VAT validation identifier

echo 'Identifier: ' . $vatResult->getIdentifier() . PHP_EOL;

// Result: Identifier: WAPIAAAAWaXGj4Ra

3.3.3. Retrieve validation date

Note: VIES service returns date and timezone, but no time, _(*18)

echo 'Date and time: ' . $vatResult->getRequestDate()->format('r') . PHP_EOL;

// Result: Date and time: Sat, 31 Aug 2019 00:00:00 +0200

3.3.4. Retrieve official trader name (not always available)

echo 'Company name: ' . $vatResult->getName() . PHP_EOL;

// Result: Company name: NV OR NATIONALE MAATSCHAPPIJ DER BELGISCHE SPOORWEGEN

3.3.5. Retrieve official trader street (not always available)

echo 'Company address: ' . $vatResult->getAddress() . PHP_EOL;

// Result: Company address: FRANKRIJKSTRAAT 56
           1060 SINT-GILLIS (BIJ-BRUSSEL)

3.3.6. Retrieve a match for trader name (not always available)

echo 'Trader name match: ' . $vatResult->getNameMatch() . PHP_EOL;

// Result: Trader name match:

3.3.7. Retrieve a match for trader company type (not always available)

echo 'Trader company type match: ' . $vatResult->getCompanyTypeMatch() . PHP_EOL;

// Result: Trader company type match:

3.3.8. Retrieve a match for trader street (not always available)

echo 'Trader street match: ' . $vatResult->getStreetMatch() . PHP_EOL;

// Result: Trader street match:

3.3.9. Retrieve a match for trader postcode (not always available)

echo 'Trader postcode match: ' . $vatResult->getPostcodeMatch() . PHP_EOL;

// Result: Trader postcode match:

3.3.10. Retrieve a match for trader city (not always available)

echo 'Trader city match: ' . $vatResult->getCityMatch() . PHP_EOL;

// Result: Trader city match:

Example code

<?php

use DragonBe\Vies\Vies;
use DragonBe\Vies\ViesException;
use DragonBe\Vies\ViesServiceException;

require_once dirname(__DIR__) . '/vendor/autoload.php';

$vies = new Vies();

$company = [
   'country_code' => 'BE',
   'vat_id' => '0203430576',
   'trader_name' => 'B-Rail',
   'trader_company_type' => 'NV',
   'trader_street' => 'Frankrijkstraat 65',
   'trader_postcode' => '1060',
   'trader_city' => 'Sint-Gillis',
];

try {
    $vatResult = $vies->validateVat(
        $company['country_code'],        // Trader country code
        $company['vat_id'],              // Trader VAT ID
        'BE',                            // Requester country code (your country code)
        '0811231190',                    // Requester VAT ID (your VAT ID)
        $company['trader_name'],         // Trader name
        $company['trader_company_type'], // Trader company type
        $company['trader_street'],       // Trader street address
        $company['trader_postcode'],     // Trader postcode
        $company['trader_city']          // Trader city
    );
} catch (ViesException $viesException) {
    echo 'Cannot process VAT validation: ' . $viesException->getMessage();
    exit (2);
} catch (ViesServiceException $viesServiceException) {
    echo 'Cannot process VAT validation: ' . $viesServiceException->getMessage();
    exit (2);
}

echo ($vatResult->isValid() ? 'Valid' : 'Not valid') . PHP_EOL;
echo 'Identifier: ' . $vatResult->getIdentifier() . PHP_EOL;
echo 'Date and time: ' . $vatResult->getRequestDate()->format('d/m/Y H:i') . PHP_EOL;
echo 'Company name: ' . $vatResult->getName() . PHP_EOL;
echo 'Company address: ' . $vatResult->getAddress() . PHP_EOL;

echo 'Trader name match: ' . $vatResult->getNameMatch() . PHP_EOL;
echo 'Trader company type match: ' . $vatResult->getCompanyTypeMatch() . PHP_EOL;
echo 'Trader street match: ' . $vatResult->getStreetMatch() . PHP_EOL;
echo 'Trader postcode match: ' . $vatResult->getPostcodeMatch() . PHP_EOL;
echo 'Trader city match: ' . $vatResult->getCityMatch() . PHP_EOL;
echo PHP_EOL;

When you run this, you will get the following result:, _(*19)

Valid
Identifier: WAPIAAAAWaYR0O8D
Date and time: 21/10/2018 02:00
Company name: NV OR NATIONALE MAATSCHAPPIJ DER BELGISCHE SPOORWEGEN
Company address: FRANKRIJKSTRAAT 56
1060 SINT-GILLIS (BIJ-BRUSSEL)
Trader name match:
Trader company type match:
Trader street match:
Trader postcode match:
Trader city match:

Community involvement

Here's a list of products or projects that have included this VIES package, _(*20)

If you have a product or a project that's using this package and you want some attribution for your work, send me an email or ping me on Twitter or Facebook., _(*21)

Docker containers

If you like to have Docker containers, you can now make use of a container designed for that purpose., _(*22)

docker run --rm -d -p 8000:18080 dragonbe/vies-web

Point your browser to localhost:8000 to use the web interface for validating VAT., _(*23)

A screenshot of VIES web application , _(*24)

Referenced on the web

Clarification on exceptions

For Greece the international country ISO code is GR, but for VAT IDN's they use the prefix EL. Thanks to Johan Wilfer for reporting this., _(*25)

Since January 1, 2021 the UK is no longer a member of the European Union and as a result, the VIES service provided by the European Commission no longer validates VAT ID's for the UK. There is one exception though and that is for Northern Ireland (XI) for which VAT ID's can be validated using this library and the EC VIES service., _(*26)

Licence

DragonBe\Vies is released under the MIT Licence. See the bundled LICENCE file for details., _(*27)

The Versions

20/05 2018

dev-master

9999999-dev https://github.com/DragonBe/vies

EU VAT numbers validation using the VIES Service of the European Commission

tool vies

EU VAT numbers validation using the VIES Service of the European Commission

dragonbe/vies

The README.md

VIES

GDPR and privacy regulation of VAT within the EU

Requirements

Installation

Usage

1. Setting it up

2. See if the VIES service is alive

If using a proxy, you can now use the following approach

3. Validate VAT

3.1. Simple usage

3.2. Advanced usage

3.3. Result methods

3.3.1. Is the VAT ID valid?

3.3.2. Retrieve the VAT validation identifier

3.3.3. Retrieve validation date

3.3.4. Retrieve official trader name (not always available)

3.3.5. Retrieve official trader street (not always available)

3.3.6. Retrieve a match for trader name (not always available)

3.3.7. Retrieve a match for trader company type (not always available)

3.3.8. Retrieve a match for trader street (not always available)

3.3.9. Retrieve a match for trader postcode (not always available)

3.3.10. Retrieve a match for trader city (not always available)

Example code

Community involvement

Docker containers

Referenced on the web

Clarification on exceptions

Licence

The Versions

dev-master

The Requires

The Development Requires

by Michelangelo van Dam

2.1.x-dev

The Requires

The Development Requires

by Michelangelo van Dam

2.1.1

The Requires

The Development Requires

by Michelangelo van Dam

dev-gdpr-update

The Requires

The Development Requires

by Michelangelo van Dam

2.1.0

The Requires

The Development Requires

by Michelangelo van Dam

dev-package-updates

The Requires

The Development Requires

by Michelangelo van Dam

dev-improving-queue-webinterface

The Requires

The Development Requires

by Michelangelo van Dam

dev-example-worker-for-offline-processing

The Requires

The Development Requires

by Michelangelo van Dam

2.0.x-dev

The Requires

The Development Requires

by Michelangelo van Dam

2.0.4

The Requires

The Development Requires

by Michelangelo van Dam

2.0.3

The Requires

The Development Requires

by Michelangelo van Dam

dev-bakame-php-feature/improve-PHP7-features

The Requires

The Development Requires