On this page

Merchant Feed API

The Merchant Feed API lets sellers upload transaction on real time or in bulks. Transactions flow automatically and securely into Lovat, giving businesses daily cash flow and tax  updates.

 

Terms and Abbreviation

API – application Programming Interface. A set of calls provided by the system calls for integration with external software products.
Merchant – the owner of an online store.
Customer – an individual who pays for goods or services.
Transaction – transfer of funds for goods or services received by the customer from the merchant.
Token – a secret string used by the system to identify the merchant and the web-site through which the transaction is registered.

API Description

Send method.
Description of the method.
The SEND method implements the reception of data on the transaction, taking into account the processing and calculation of VAT and system charges.

PUT

Referrer URL

The method is available at the following URL:

https://merchant.vatcompliance.co/api/1/send/{access_token}?if_digital={true/false}&if_vat_calculate={true/false}

Call Options

Call parameters are divided into two types:

  • Path parameters (token)
  • Query parameters (transaction data)

The token is generated in the internal account of the merchant at the first stage of adding the web-site. You can get it from your manager or find it in the Section Store –Settings.
The request parameters are generated by the merchant and sent to the server using the POST method in the application / x-www-form-urlencoded or application / json format.

Digital services

Parameter Type/Example Example Description Validation
transactions_id String/555-yyy Transaction ID Maximum 255 characters. Not an empty value
transaction_date Date/2021-01-09 Date of the transaction
in accordance with
ISO 8601		 Not an empty value
transaction_sum String/25 Transaction Amount Maximum 45 characters. Not an empty value
customer_ip String/127.0.0.1 Customer’s IP address Maximum 45 characters
currecy String/“usd”, “eur”, “rub”, “gbp” Transaction Currency Maximum 3 characters. Not an empty value
customer_phone_number String/“+1 AAA BBB BB BB” Customer’s phone number Maximum 100 characters.
arrival_country String/“GBR” All countries are specified as strings according to ISO 3166-1 alpha-3 Maximum 3 characters
arrival_city String/“London” Arrival city Maximum 255 characters
arrival_address_line String/“Peckham Road” Arrival address line Maximum 255 characters
transaction_status String/“Success”, “Charge back”, “refund”,“Movement own goods” Transaction Status Not an empty value
service_code String/“1” Merchant service type code – if the merchant does not send data on the type of service provided, the transaction is assigned the nominal principal type of merchant’s service that was specified at registration Maximum 255 characters. Not an empty value
bank_card_number String/“1234-****-****-****” Bank card number of the buyer Maximum 19    characters
payment_operator String/“payonline” paypal” Payment Operator Maximum 45 characters. Not an empty value
payment_method_country String/“USA” Payment option by country. All countries are specified as strings according to ISO 3166-1 alpha-3 Maximum 3 characters. Not an empty value
billing_country String/“USA” Billing country (address of the payment owner). All countries are specified as strings according to ISO 3166-1 alpha-3 Maximum 3 characters. Not an empty value
billing_address String/“111 First Street,Saratoga, CA 95070, US” Billing address (address of the payment owner) Maximum 255 characters. Not an empty value
arrival_zip String Required for US orders: Postal code where the order shipped to Required for US orders. Maximum 50 characters
exemption_type Enum For US orders only. Types used: wholesale, government, educational, marketplace, other, or non_exempt Optional. Maximum 50 characters
POST

Server Response Code

The response to the query uses the basic HTTP code:

Code Explanation Response content
200 OK Request Processed Request Processed
400 BadRequest Invalid request { error : “Problem with data” }
401 Unauthorized Unauthorized access { error : “Token is invalid.” }

Example query for digital services:
Sample request from the console

Command Line

curl -v POST 'http://https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=true' --header "Content-Type: application/json" 
-d '{ 
"transaction_id": " ttt4565-85546", 
"transaction_datetime": "2017-01-09T08:27:22 +00:00", 
"transaction_sum": 25.99, 
"customer_ip": "127.0.0.1", 
"customer_phone_number": "+7 677 ** * **",

Command line

require "uri"
require "net/http"

url = URI("https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=true")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
form_data = [['transaction_id', 'ttt4565-85546'],['transaction_datetime', '2017-01-09T08:27:22 +00:00'],['transaction_sum', '25.99'],['customer_ip', '127.0.0.1'],['customer_phone_number', '+7 677   *']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
Command line

import requests

url = "https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=true"

payload={'transaction_id': 'ttt4565-85546',
'transaction_datetime': '2017-01-09T08:27:22 +00:00',
'transaction_sum': '25.99',
'customer_ip': '127.0.0.1',
'customer_phone_number': '+7 677   *'}
files=[

]
headers = {
  'Content-Type': 'application/json'
}

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

/$curl = curl_init();

curl_setopt_array($curl, [
	CURLOPT_URL => 'https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&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 => [
		'transaction_id' => 'ttt4565-85546',
		'transaction_datetime' => '2017-01-09T08:27:22 +00:00',
		'transaction_sum' => '25.99',
		'customer_ip' => '127.0.0.1',
		'customer_phone_number' => '+7 677   *'
	],
	CURLOPT_HTTPHEADER => [
		'Content-Type: application/json'
	],
]);/

Command line

/var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=true',
  'headers': {
    'Content-Type': 'application/json'
  },
  formData: {
    'transaction_id': 'ttt4565-85546',
    'transaction_datetime': '2017-01-09T08:27:22 +00:00',
    'transaction_sum': '25.99',
    'customer_ip': '127.0.0.1',
    'customer_phone_number': '+7 677   *'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});/
Command line

using System;
using System.Net;

class Program
{
    static void Main(string[] args)
    {
        var url = "https://omp.vatcompliance.co/api/omp/feed/6cec387781a94425b401206d1710801a?if_digital=true&if_vat_calculate=true";
        var data = new System.Collections.Specialized.NameValueCollection
        {
            { "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" },
            { "vat_percent", "20.00" },
            { "vat", "28.73" },
            { "departure_country", "AUS" }
        };

        using (var client = new WebClient())
        {
            var responseBytes = client.UploadValues(url, data);
            var response = System.Text.Encoding.UTF8.GetString(responseBytes);
            Console.WriteLine(response);
        }
    }
}

Command line

/OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("transaction_id","ttt4565-85546")
  .addFormDataPart("transaction_datetime","2017-01-09T08:27:22 +00:00")
  .addFormDataPart("transaction_sum","25.99")
  .addFormDataPart("customer_ip","127.0.0.1")
  .addFormDataPart("customer_phone_number","+7 677   *")
  .build();
Request request = new Request.Builder()
  .url("https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=true")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();/

Command line

/package main

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

func main() {

  url := "https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=true"
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  _ = writer.WriteField("transaction_id", "ttt4565-85546")
  _ = writer.WriteField("transaction_datetime", "2017-01-09T08:27:22 +00:00")
  _ = writer.WriteField("transaction_sum", "25.99")
  _ = writer.WriteField("customer_ip", "127.0.0.1")
  _ = writer.WriteField("customer_phone_number", "+7 677   *")
  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.Add("Content-Type", "application/json")

  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))
}/

Goods

Parameter Type/ Example Example Description Validation
transactions_id String/ 555-yyy Transaction ID Maximum 255 characters. Not an empty value
transaction_date Date/ 2021-01-09 Date of the transaction
in accordance with
ISO 8601		 Not an empty value
transaction_sum String / 25 Transaction Amount Maximum 45 characters. Not an empty value
currency String/“GBP”,“EUR”, “RUB” All currencies are specified as strings according to ISO 4217 Maximum 3 characters. Not an empty value.
arrival_country String/“GBR” All countries are specified as strings according to ISO 3166-1 alpha-3 Maximum 3 characters
arrival_city String/“London” Arrival city Maximum 255 characters
arrival_address_line String/“Peckham Road” Arrival address line Maximum 255 characters
transaction_status String/“Success”, “Charge back”, “refund”, “Movement own goods” Transaction Status Not an empty value
good_code String/“62160000” Code of a good according to EU’s eight-digit coding system The Combined Nomenclature (CN) Maximum 8 characters
tax_rate Float/20.00 Tax rate Maximum 8 characters
tax_amount Float/28.73 Tax Amount Float
departure_country String/“AUS” Payment option by country. All countries are specified as strings according to ISO 3166-1 alpha-3 Maximum 3 characters. Not an empty value
taxable_jurisdiction String/“GBR” Payment option by country. All countries are specified as strings according to ISO 3166-1 alpha-3 Maximum 3 characters
buyer_vat_number String Buyer vat number EU Maximum 255 characters
departure_city String Departure city Optional. Maximum 255 characters
departure_state String For US, Canada, UK: Two-letter ISO state code where the order shipped from Optional. Maximum 50 characters
departure_zip String Required for US orders: Postal code where the order was shipped from. Required for US orders. Maximum 50 characters
taxable_state String For US, Canada, UK: Two-letter ISO state code where the order shipped from Optional. Maximum 50 characters
taxable_city String Taxable city Optional. Maximum 255 characters
taxable_zip String Required for US orders: Postal code Required for US orders. Maximum 50 characters
arrival_zip String Required for US orders: Postal code where the order shipped to Required for US orders. Maximum 50 characters
exemption_type Enum For US orders only. Types used: wholesale, government, educational, marketplace, other, or non_exempt Optional. Maximum 50 characters

Example query for digital services:
Sample request from the console

Command Line

curl-v POST
https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false
--header "Content-Type: application/json" \
-d '{
                "transaction_id ": " ttt4565-85546",
                "transaction_datetime": "2017-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",
}'

Command line

require 'net/http'
require 'json'

params = {
  "transaction_id" => "ttt4565-85546",
  "transaction_datetime" => "2017-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"
}

url = URI.parse('https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url.path)
request.body = params.to_json
request['Content-Type'] = 'application/json'

response = http.request(request)
Command line

import requests
import json

params = {
    "transaction_id": "ttt4565-85546",
    "transaction_datetime": "2017-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"
}

url = 'https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false'
headers = {'Content-Type': 'application/json'}

response = requests.post(url, data=json.dumps(params), headers=headers)

print(response.text)

Command line

$params = [
	"transaction_id " => "ttt4565-85546",
	"transaction_datetime" => "2017-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"
];
$curl = curl_init();

curl_setopt_array($curl, array(
	CURLOPT_URL => 'https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false',
	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 => json_encode($params),
	CURLOPT_HTTPHEADER => array(
		'Content-Type: application/json'
	),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Command line

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false',
  'headers': {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"transaction_id ":"ttt4565-85546","transaction_datetime":"2017-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,"tax_amount":28.73,"departure_country":"AUS"})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Command line

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var httpClient = new HttpClient();
        
        var url = "https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false";

        var payload = new
        {
            transaction_id = "ttt4565-85546",
            transaction_datetime = "2017-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"
        };

        var jsonPayload = Newtonsoft.Json.JsonConvert.SerializeObject(payload);
        var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

        var response = await httpClient.PostAsync(url, content);
        
        var responseContent = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseContent);
    }
}

Command line

import org.json.JSONObject;
import java.io.IOException;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            String urlString = "https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false";
            URL url = new URL(urlString);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);

            JSONObject params = new JSONObject();
            params.put("transaction_id", "ttt4565-85546");
            params.put("transaction_datetime", "2017-01-09T08:27:22+00:00");
            params.put("transaction_sum", 158.04);
            params.put("currency", "GBP");
            params.put("arrival_country", "GBR");
            params.put("arrival_city", "London");
            params.put("arrival_address_line", "Peckham Road");
            params.put("transaction_status", "Success");
            params.put("good_code", "62160000");
            params.put("tax_rate", 20.00);
            params.put("tax_amount", 28.73);
            params.put("departure_country", "AUS");

            try (OutputStream outputStream = connection.getOutputStream()) {
                byte[] input = params.toString().getBytes("utf-8");
                outputStream.write(input, 0, input.length);
            }

            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                StringBuilder response = new StringBuilder();
                byte[] buffer = new byte[4096];
                int bytesRead;
                while ((bytesRead = connection.getInputStream().read(buffer)) != -1) {
                    response.append(new String(buffer, 0, bytesRead, "utf-8"));
                }
                System.out.println(response.toString());
            } else {
                System.out.println("Error: " + responseCode);
            }

            connection.disconnect();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Command line

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false"
  method := "POST"

  payload := strings.NewReader(`{
    "transaction_id ": "ttt4565-85546",
    "transaction_datetime": "2017-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"
}`)

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

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")

  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))
}
GET

Services Code List

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
eNewspapers 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