Location Evidence
Use location evidence to model the evidence that is collected to determine tax for digital goods.
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'
Updated about 1 month ago