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:

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:

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”
}]