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 countries and 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.
• The Reverse Charge mechanism enables a seller to shift obligation to collect tax from the seller to the buyer. The buyer subsequently pays and deducts the tax simultaneously in their tax return. Reverse charge is only supported for B2B sales and the tax authorities place onus on the seller to validate their buyer’s tax registration before utilizing the Reverse Charge mechanism.
• You can use the service to verify their buyer’s business status before commencing commercial relationship.

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. For more information, see B2B Transaction Processing.

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:

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.

Validating Multiple Tax IDs for Canada

In Canada, you may need to validate both a Goods and Services Tax (GST)/Harmonized Sales Tax (HST) Tax ID and a Quebec State Tax (QST)/Provincial State Tax (PST) Tax ID in the same request.

To do so, you need to add a nested list using the buyer_tax_number field. For example:

"buyer_tax_numbers": [

         {"buyer_tax_number": "119364511"},

         {"buyer_tax_number": "7273121"}

     ],

Supported Countries and Regions

For more information about this, see Supported Countries and Regions.