B2B Transaction Processing

Business-to-Business (B2B) transactions are those where both the buyer and seller are businesses. This is based around Tax ID validation of the Tax ID (such as a VAT number) that is supplied by the buyer.

The service uses the VAT Information Exchange Service (VIES) service to validate the IDs.

Validating Tax IDs Individually (Vertex Validator)

You can use the Validate VAT number request to validate Tax IDs. For more information, see Validate VAT number.

For example, you can use a GET operation and the following request to validate an ID for a specific country:

https://services.taxamo.com/api/v2/tax/vat_numbers/:tax_number/validate?country_code=:country_code

where

  • :tax_number is the number that you want to validate.
  • :country_code is the country code for the country where you want to validate the number.

For more information, see Vertex Validator.

Validating Tax IDs in Transactions

You can also validate a Tax ID as part of a transaction using the Store transaction request. For more information, see Store transaction.

For example, the following JSON specifies an ID from a business based in the Czech Republic in the "buyer_tax_number": "CZ12345678" field.

{
  "transaction": {
    "buyer_name": "John Smith",
    "currency_code": "EUR",
    "status":"N",
    "transaction_lines": [
      {
        "custom_id": "Test",
        "amount": 100,
        "quantity": 1
      }
    ],
    "buyer_tax_number": "CZ12345678",
    "order_date": null,
    "billing_country_code": "CZ",
    "force_country_code": "CZ"
  }
}

If the Tax ID is not valid, the system behavior can differ depending on your country settings and your Tax ID Cache settings. Sometimes, it can reject the transaction. In some cases, it can treat the transaction as a Business-to-Customer (B2C) transaction.

If the Tax ID is valid, the service might return the address of the business as per the authority's records. For example:

"invoice_address": {
    "freeform_address": "Prague St. 314",
    "country": "CZ"
}

This value overwrites the value that is used in the following fields:

  • transaction.invoice_address
  • transaction.invoice_address.freeform_address
  • transaction.invoice_address.country
  • transaction.buyer_name

In some cases, the tax authority does not reveal this information so it may not be returned. In these responses, the tax authority can redact specific information.

Redacted Responses

If the tax authority does disclose a specific piece of information, the service returns --- in the field. For example, the following request is validating a number in Germany:

api/v2tax/vat_numbers/317065484/validate?country_code=de

This returns the following response:

{
    "invoice_address": {
        "freeform_address": "---",
        "country": "DE"
    },
    "buyer_tax_number": "123456789",
    "tax_deducted": true,
    "billing_country_code": "DE",
    "buyer_tax_number_format_valid": true,
    "warnings": null,
    "buyer_tax_number_valid": true,
    "buyer_tax_number_normalized": "123456789",
    "buyer_name": "---"
}

The following screenshot shows how these values are returned by VIES:

22422242

VIES Hidden Fields

Tax ID Cache Control Flags

The service caches list of Tax IDs that are used to validate IDs.

You can use Control Flags in your requests to adjust the settings that control how values are stored in the cache:

SettingDetailsDescription
b2b-number-service-timeoutms-<country or region>Maximum Length: 64
Default Value: 20000ms
Minimum Value: 10000ms
Maximum Value: 30000ms
This setting specifies the timeout value for the service that validates the number.
For example if the setting is b2b-number-service-timeoutms-EU: 20000, EU validations will wait 20 seconds for a response from VIES.
b2b-number-service-expiry-daysDefault Value: 30
Minimum Value: 0
Maximum Value: 365
This setting specifies the number of days that before the cached data is refreshed.
You can set it to 0 to force the service to bypass the cache and use the validation service in real-time.
b2b-number-service-on-errorPossible Values: accept or block
Maximum Length: 16
If set to accept, the transaction is treated as successful even if the validation check fails due to a timeout or any other issue.
If set to block, the transaction is blocked, the response will be a HTTP 400 error with a warning.

Here is an example of a block response with a warning:

"errors": [
        "Business number validation service unavailable. Please re-submit your request later."
],
"warnings": [
    {
        "type": "ukraine-b2b-error",
        "message": "connect timed out"
    }
]

Error Responses

The verification service can return errors in a number of situations. For example, if the service is unavailable due to maintenance., the service can return a 40X HTTP response. For example:

"warnings":[{
    "type":"vies-error",
    "message":"cabinet.tax.gov.ua service is not available”
}]