Vertex Validator

Vertex Validator offers a real-time business-to-business (B2B) validation service that fits into your users’ workflows and helps fulfill several use cases. This service is especially valuable as the tax treatment can vary from the business-to-consumer (B2C) channel in many locations.

The service's API provides a way to manage your tax ID verification across multiple regions. This helps you to meet demanding and diverse requirements of various tax authorities.

The solution offers the following capabilities:

  • Support for more than 50 regions
  • Support for multiple validation types. For example, real-time, scheduled and batch validations are all supported.
  • Validation can be configured to require a CAPTCHA.
  • Dual number validation. For example, in Canada it can validate both GST and HST.
  • Some sellers are required to validate a businesses’ tax number before applying a reverse charge and zero rating the transaction. Vertex’s B2B validation service supports this.
  • Customers who may want to integrate supplier verification into their supplier onboarding process can also utilize this service.
  • Validating numbers programmatically and reliably helps ensure that you have the correct number tax numbers that you may need later for reclaiming tax.

Users send their business or tax numbers for validation. This number is sent to Vertex using the API. Vertex checks this number against a database or using a syntax check. The API returns a true or false response.

Integration

If you are an existing Vertex Advantage, Vertex Advantage Plus or Taxamo Assure by Vertex customer, this module is included and integrated alongside the other features. Tax IDs are validated as part of the process for Business-to-Business (B2B) transactions, as specified in your configuration.

If you are solely a Vertex Validator customer, you need to use the API to integrate the service with your webstore.

For Vertex Validator customers, you need to contact support to get a user before you can integrate with the service. After you get this user, log in to the Merchant Portal and retrieve your access token. You will need this to be able to make requests.

Integrating with the API

To integrate the service, you use the Validate VAT number request.

To use this request, send a GET operation to the following endpoint URL:

https://services.taxamo.com/api/v2/tax/vat_numbers/:tax-number/validate

where :tax-number is the Tax ID that you want to verify.

The following table lists the parameters that you can include with the the request:

Parameter

Description

private_token

Private token.

tax_number

The Tax ID that you wish to validate.

country_code

The code for the country.

Supported Countries and Regions

Country or Region

Supported

European Union (EU) (27 total)

Yes

Albania

No

Australia

Yes

Bahrain

Contact support

Canada

Yes

Columbia

No

Egypt

No

India

Yes

Iceland

No

Japan

Yes

Morocco

No

New Zealand

Yes

Norway

Yes

Saudi Arabia

Contact support

Serbia

No

South Africa

No

South Korea

Yes

Switzerland

No

Taiwan

Yes

Turkey

Yes

UAE

Contact support

USA

No

Tax Number Validation

There are several methods which can be used to validate the tax number:

  • Format Check: Vertex validates that the number uses the correct format. The validity of the number itself is not checked.
  • Tax Authority Validation: Vertex validates the number by checking against the database that is maintained by the tax authority.
  • CAPTCHA Validation: Some tax authorities require that a CAPTCHA is also solved before the tax number is validated. Vertex supports this by providing a CAPTCHA to the user who requests the validation.

VAT Status Caching

After a tax number is validated, its status is stored indefinitely in the cache. This cached status can be used to facilitate validation without the need to check the tax authority’s database again.

The caching mechanism searches 30 days of data by default. However, you can change this by using a control flag in each request. For example, you might receive a response that states that the VIES lookup has timed out. This could mean that there is not an entry for the last 30 days and you may want to extend the length of the search period to 90 days.

If you do not want to use the cache at all, you can ask support to set the search period value to 0.

Support can change this setting in your account settings, if you prefer.

The following example shows a retention period that is set to 30 days using the control flag:

{ "private_token": "*******",
  "transaction": {
    "currency_code": "EUR",
    "control_flags": [
      {
        "key": "b2b-number-service-cache-expiry-days",
        "value": "30"
      }
    ],
    "billing_country_code": "NO",
    "transaction_lines": [
      {
        "custom_id": "1",
        "amount": 100
      }
    ],
    "buyer_ip": "",
    "buyer_tax_number": "NO123456789",
  }
}

Configuring CAPTCHA Validation

Some tax authorities require that users who request a validation solve a CAPTCHA before the number is validated.

You can use one of the following methods to configure this:

  • Checkout Form: If you use the Checkout Form, the CAPTCHA image is displayed to users and the information is passed to the tax authority.
  • API: The API can provide a Base64 image of the CAPTCHA that can be presented to the user. When solved by the user, the solution is returned to the service and it is used to facilitate the validation of the tax number with the tax authority.

📘

Information

For some integrations, these options may not suit as you may not want to present your users with a CAPTCHA. If you think this is the case for you, contact support to explore possible alternatives.

The API response is either true or false. True indicating that the number has been successfully validated.

The validation service is facilitated by a third-party service provider. If there is an error with this service, a warning message is returned. For example:

[{"type": "b2b-error", "message": "...any other error..."}], ["egr.by service is not available"]

When the number cannot be validated by the third-party service, the buyer_tax_number_valid field is returned as null.


Did this page help you?