Location evidence is used for processing transactions that involve digital goods. It can be used in manual or automatic modes.

Location Evidence Processing

The order in which location evidence is processed is specific to your configuration so as to best reflect your needs.

In general, the service will always try to find 1 or multiple matching pieces of evidence.

Here is an example hierarchy:

VAT or GST number: A VAT or GST number can be evidence of the buyer's location.
Self-declaration: Self-declaration is typically used to confirm the location derived from other pieces of evidence. However, it can also be used as the sole piece of evidence.
Other commercially relevant information: Other information that can be used to derive evidence.
Payment country: The country information from the buyer's payment information. For example, a BIN.
IP address: The buyers IP address can be used to determine location.
Billing country: The buyer can specify their billing country and this can be used as evidence.

Fields

For each evidence kind, the evidence_value field should be provided. If the evidence resolves correctly, the service will return updated information for each piece of evidence. This information will contain the following fields:

Field	Description
`evidence[by_tax_number].evidence_value`	The customer's Tax ID such as a VAT ID. The ID is checked by Vertex Validator and a validation result is returned.
`evidence[by_ip].evidence_value`	The customer's IP address used to make the purchase.
`evidence[by_cc].evidence_value`	The customer's credit card BIN (Bank Identification Number).
`evidence[by_billing].evidence_value`	The customer's billing country, a 2-letter ISO code.
`evidence[by_payment_method].evidence_value`	If the payment method has provided country evidence, please specify the 2-letter ISO country code here (for example GB)
`evidence[by_self_declaration].evidence_value`	If the customer has provided a self-declared country code, please specify the 2-letter ISO country code here (for example GB)
`evidence[ other_commercially_relevant_info].evidence_value`	If the payment method has provided country evidence, please specify the 2-letter ISO country code here (for example GB).

Manual and Automatic Modes

You may want to manually send your customers’ location information to Vertex or you may want Vertex to automatically derive this information from the location evidence.

The service functions in one of the following modes to facilitate this:

Manual: When this mode is set to manual, Vertex does not verify or derive customer location based on evidence. Instead, the location is specified by you (in the country_code field) in the request that is sent to the API.
Automatic: When this mode is set to automatic, Vertex derives the customer’s location based on location evidence.

To enable manual mode, you need to add manual_mode=true to your requests. For example:

$ curl -X 'POST' -H "Content-Type: application/json" -d \
 '{
        “manual_mode”: “true”
        "transaction": {
          "transaction_lines": [
              {
                  "custom_id": "line1",
                  "amount": 100
              }
          ],
          "buyer_ip": "109.121.15.46",
	   “status”: “C”	
          "currency_code": "EUR",
          "billing_country_code": "BE",
          "buyer_credit_card_prefix": "424242424"
      },
      "private_token": "priv_***********"
  }' \
 'https://services.taxamo.com/api/v2/transactions'