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 a mix of services (such as the VAT Information Exchange Service (VIES) in the Europe) 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/123456789/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:

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:
Setting | Details | Description |
---|---|---|
b2b-number-service-timeoutms-<country or region> | Maximum Length: 64 Default Value: 2000ms Minimum Value: 1000ms Maximum Value: 3000ms | This setting specifies the timeout value for the service that validates the number. For example if the setting is b2b-number-service-timeoutms-EU: 2000 , EU validations will wait 2 seconds for a response from VIES. |
b2b-number-service-expiry-days | Default 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-error | Possible 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"
}
]
Here is an example of the control flags in an example transaction:
{
"transaction": {
"buyer_name": "John Smith",
"currency_code": "EUR",
"status":"N",
"invoice_address": {
"region": "",
"city": "",
"postal_code": "",
"street_name":"",
"address_details":""
},
"transaction_lines": [
{
"custom_id": "Test",
"amount": 100,
"quantity": 1
}
],
"control_flags": [
{
"key": "b2b-number-service-expiry-days",
"value": "30"
},
{
"key": "b2b-number-service-on-error",
"value": "accept"
}
],
"buyer_tax_number": "CZ12345678",
"order_date": null,
"billing_country_code": "CZ",
"buyer_ip":"192.168.0.1"
}
}
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”
}]
Updated about 1 month ago