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.
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.
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 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.
|
Parameter |
Type / Example |
Example Description |
Validation |
|
transaction_id |
String/ 555-yyy | Transaction ID | Maximum 255 characters. Not an empty value. |
| transaction_datetime |
DateTime / 2017-01-09T08:27:22 +00:00 |
Date and time of the transaction in accordance with ISO 8601 GMT |
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. |
| currency | String / “usd”, “eur”, “rub”, “gbp” | Transaction Currency |
Maximum 3 characters. Not an empty value. |
|
customer_phone_number |
String / “+7 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. |
The response to the query uses the basic HTTP code:
|
Code |
Explanation |
Response content |
|
200 OK |
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
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 ** * **",
|
Parameter
|
Type / Example |
Example Description |
Validation |
|
transaction_id |
String/ 555-yyy |
Transaction ID |
Maximum 255 characters. Not an empty value. |
|
transaction_datetime |
DateTime / 2017-01-09T08:27:22 +00:00 |
Date and time of the transaction in accordance with ISO 8601 GMT |
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. |
|
vat_percent |
Float / 20.00 |
vat percent |
Maximum 8 characters. |
|
vat |
Float / 28.73 |
VAT 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. |
Example query for goods:
Sample request from the console
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",
"vat_percent": 20.00,
"vat": 28.73,
"departure_country" : "AUS",
}'
|
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 |
18 |
|
gambling |
19 |
|
supply of goods |
20 |
|
other digital |
21 |