On this page

OMP Feed API

Allow marketplaces seamlessly integrate with tax calculation platform Lovat.

To integrate OMP Feed API:

  1. Register a Lovat OMP Account.
  2. Fill a company profile.
  3. Choose a plan.
  4. Set up Webhooks.
  5. Get a token.
  6. Set tax rules.

API Reference

Lovat API uses the REST architecture. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. The API always responds in the JSON format, including cases of errors.

Authentication

Authentication to the OMP API is performed via HTTP header basic authentication. Subscribers need to provide a token as the basic authentication value. If you’re new to Lovat, you’ll need to sign up for an account to get your API key.  The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.

URL

  • Production Region

https://omp.vatcompliance.co/api/omp – OMP Feed API, OMP Tax rate API

  • Test Region

sandbox.vatcompliance.co/api/omp

POST

Method

The request type: POST
https://omp.vatcompliance.co/api/omp/feed/{access_token}?if_digital={true/false}&if_vat_calculate={true/false}

JSON Params

Parameter Type Description Required
merchant_id String Unique identifier of the merchant Required
transaction_id String Maximum 255 characters. Required
parent_transaction_id String For refunds and returns Optional
inv_number String Tax invoice number
customer_ip String Customer’s IP address Optional
сurrency String Transaction currency. Three-letter currency code per ISO 4217. Required
transaction_datetime Date and time of the transaction in accordance with ISO 8601 GMT Required
transaction_sum Float Total amount of the order, excluding shipping Required
transaction_status String Sale/refund/return Required
customer_phone_number String Optional
arrival_country String A country where the order shipped to. Three-letter uppercase country code per ISO 3166-1 alpha-3 Required
arrival_city String Arrival city Optional
arrival_zip String ZIP/Postcode, required for all US orders Optional
arrival_address_line String Arrival address line 1 Optional
departure_country String Three-letter ISO country code of the country where the order shipped from. All countries are specified as strings according to ISO 3166- 1 alpha-3 Required
service_code String Required for digitally supplied services. Tax categories of digital services
good_code String code of a good according to EU’s eight-digit coding system The Combined Nomenclature (CN) Optional
tax_amount Float Tax Amount Optional
tax_rate Float Tax rate Optional
vat_number_of_buyer String Tax  number of buyer Optional
buyer_name String Optional
taxable_jurisdiction String All countries are specified as strings according to ISO 3166- 1 alpha-3 Optional
deemed Bool True / False Optional
departure_city String Departure city Optional
departure_state String For US, Canada, UK: Two-letter ISO state code where the order shipped from Optional
departure_zip String Required for US orders: Postal code where the order was shipped from. Required for US orders
taxable_jurisdiction String Payment option by country. All countries are specified as strings according to ISO 3166-1 alpha-3 Optional
taxable_state String For US, Canada, UK: Two-letter ISO state code where the order shipped from Optional
taxable_city String Taxable city Optional
taxable_zip String Required for US orders: Postal code Required for US orders
exemption_type Enum For US orders only. Types used: wholesale, government, educational, marketplace, other, or non_exempt Optional

 

Requests and Responses

The requests to Lovat API must:

HTTP status: 200 (OK)

be sent over HTTPS, use TLS 1.2 or higher, contain authentication parameters,

Request Example

Command Line

/curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' 
-d '{ 
   "transaction_id": "ttt4565-85546",
   "merchant_id": "678345101",
   "merchant_establishment_country_id": "DEU",
   "transaction_datetime": "2020-01-09T08:27:22 +00:00",
   "transaction_sum": 158.04,
   "currency": "GBP",
   "arrival_country" : "GBR",
   "arrival_city" : "London",
   "arrival_address_line" : "Peckham Road",
   "transaction_status" : "Success",
   "good_code": "62160000",
   "tax_rate": 20.00,
   "tax_amount": 28.73,
   "departure_country" : "AUS"
 }' 
'https://omp .vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true/

Command line

/require "uri"
require "net/http"

url = URI("https://omp.vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
form_data = [['transaction_id', 'ttt4565-85546'],['merchant_id', '678345101'],['merchant_establishment_country_id', 'DEU'],['transaction_datetime', '2020-01-09T08:27:22 +00:00'],['transaction_sum', '158.04'],['currency', 'GBP'],['arrival_country', 'GBR'],['arrival_city', 'London'],['arrival_address_line', 'Peckham Road'],['transaction_status', 'Success'],['good_code', '62160000'],['tax_rate', '20.00'],['tax_amount', '28.73'],['departure_country', 'AUS']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body
/
Command Line

/import requests
url = "https://omp.vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true"

payload={'transaction_id': 'ttt4565-85546',
'merchant_id': '678345101',
'merchant_establishment_country_id': 'DEU',
'transaction_datetime': '2020-01-09T08:27:22 +00:00',
'transaction_sum': '158.04',
'currency': 'GBP',
'arrival_country': 'GBR',
'arrival_city': 'London',
'arrival_address_line': 'Peckham Road',
'transaction_status': 'Success',
'good_code': '62160000',
'tax_rate': '20.00',
'tax_amount': '28.73',
'departure_country': 'AUS'}
files=[

]
headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)/

Command line

/ 'https://omp.vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('transaction_id' => 'ttt4565-85546','merchant_id' => '678345101','merchant_establishment_country_id' => 'DEU','transaction_datetime' => '2020-01-09T08:27:22 +00:00','transaction_sum' => '158.04','currency' => 'GBP','arrival_country' => 'GBR','arrival_city' => 'London','arrival_address_line' => 'Peckham Road','transaction_status' => 'Success','good_code' => '62160000','tax_rate' => '20.00','tax_amount' => '28.73','departure_country' => 'AUS'),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;/

Command line

/var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://omp.vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true',
  'headers': {
  },
  formData: {
    'transaction_id': 'ttt4565-85546',
    'merchant_id': '678345101',
    'merchant_establishment_country_id': 'DEU',
    'transaction_datetime': '2020-01-09T08:27:22 +00:00',
    'transaction_sum': '158.04',
    'currency': 'GBP',
    'arrival_country': 'GBR',
    'arrival_city': 'London',
    'arrival_address_line': 'Peckham Road',
    'transaction_status': 'Success',
    'good_code': '62160000',
    'tax_rate': '20.00',
    'tax_amount': '28.73',
    'departure_country': 'AUS'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});/

Command line

/* Your code... */

Command line

/OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("transaction_id","ttt4565-85546")
  .addFormDataPart("merchant_id","678345101")
  .addFormDataPart("merchant_establishment_country_id","DEU")
  .addFormDataPart("transaction_datetime","2020-01-09T08:27:22 +00:00")
  .addFormDataPart("transaction_sum","158.04")
  .addFormDataPart("currency","GBP")
  .addFormDataPart("arrival_country","GBR")
  .addFormDataPart("arrival_city","London")
  .addFormDataPart("arrival_address_line","Peckham Road")
  .addFormDataPart("transaction_status","Success")
  .addFormDataPart("good_code","62160000")
  .addFormDataPart("tax_rate","20.00")
  .addFormDataPart("tax_amount","28.73")
  .addFormDataPart("departure_country","AUS")
  .build();
Request request = new Request.Builder()
  .url("https://omp.vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true")
  .method("POST", body)
  .build();
Response response = client.newCall(request).execute();/

Command line

/package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://omp.vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true"
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  _ = writer.WriteField("transaction_id", "ttt4565-85546")
  _ = writer.WriteField("merchant_id", "678345101")
  _ = writer.WriteField("merchant_establishment_country_id", "DEU")
  _ = writer.WriteField("transaction_datetime", "2020-01-09T08:27:22 +00:00")
  _ = writer.WriteField("transaction_sum", "158.04")
  _ = writer.WriteField("currency", "GBP")
  _ = writer.WriteField("arrival_country", "GBR")
  _ = writer.WriteField("arrival_city", "London")
  _ = writer.WriteField("arrival_address_line", "Peckham Road")
  _ = writer.WriteField("transaction_status", "Success")
  _ = writer.WriteField("good_code", "62160000")
  _ = writer.WriteField("tax_rate", "20.00")
  _ = writer.WriteField("tax_amount", "28.73")
  _ = writer.WriteField("departure_country", "AUS")
  err := writer.Close()
  if err != nil {
    fmt.Println(err)
    return
  }


  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Set("Content-Type", writer.FormDataContentType())
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}/

Tax categories of digital services

Audio/visual content 1
Live streaming 2
Telephone services 3
Internet telephone services 4
Call management services 5
Paging services 6
Internet access 7
Images 8
Music 9
Games 10
E-newspapers 11
Web hosting 12
Distance maintenance of programmes 13
Advertising space on a website 14
E-books 15
Licenses 16
Dating 17
Distance education (pre-recorded) 18
Gambling 19
SaaS 20
Online education live (live webinars, one-to ones)
21