How to connect custom platform for cross-border compliance to EAS via API for VAT calculation

EAS Solutions powerful tax engine can also be used for VAT calculations

This document describes methods and processes for connecting to the “EAS EU Compliance solution” developed by Easy Access System Project OU via direct API integration.

Online VAT calculation to be used when  it can be injected into checkout process between Delivery option selection and payment step,

If this approach not applicable for you store configuration please try to use this approach API description for manual connection to EAS system (post sale approach)

General

Full API description available at https://api-doc.easproject.com

 

Testing API base URL	https://internal1.easproject.com/api/
Production API base URL	https://manager.easproject.com/api/

 

Authorization

EAS REST API uses oAuth 2.0

Authorization end point	/auth/open-id/connect
Grant type	Client credentials Use client_id and client_secret for authorization. Credentials for test environment should be request from EAS Project support team.
Scope	openid
Response:200 OK	Response contains Authorization token that should be used when any API method is accessed.

Creating order in the EAS system

Before customer goes to the payment stage in the store (it is assumed that all items are added to the cart and delivery address and delivery name collected) need to send Order information to the EAS system for calculating customs duties and VAT.

Follow next steps to process order via EAS system:

1. Send request for calculating Customs Duties and taxes

End point	/calculate
Authorization	Bearer Authorization token
x-redirect-uri	URL in your system that will be used when B2B client will Agree with the confirmation page. When client agrees, checkout token will be sent to the provided URL and client will be redirected to that URL. (usually it is checkout page - payment step)
x-decline-uri	URL in your store that will be used when B2B client will decline with the confirmation page. When client declines, he will be redirected to the desired URL
Body	To be provided JSON with order information
Response:200 OK	x-redirect-uri/?eas_checkout_token=JWT_TOKEN_WITH_ORDER_DATA

Order JSON description

JSON	Comments (additionally to Swagger)
{
"external_order_id": "#150097",	Order number in your system, might be empty at this step
"payment_currency": "USD",	Payment currency should be the same, that will be used by client during payment process. ISO 3 alpha code.
"recipient_title": "Mr.",	Value from the list [ Mr., Ms./Mrs., Dr., Prof ]
"recipient_first_name": "Alejandra",	End customer first name
"recipient_last_name": "Besuregard diaz",	End customer last name
"recipient_company_name": "",	This will be skipped if  is_delivery_to_person = true End customer company name
"recipient_company_vat": "",	This will be skipped if  is_delivery_to_person = true End customer company VAT.
"is_delivery_to_person": true,	If delivered to Company need to set false When B2B order processed our system will verify recipient_company_vat and separate verification page will be displayed. Link to that page will be send in the response instead of landed cost token. When customer confirms VAT number validation customer will be redirected to the x-redirect-uri/?eas_checkout_token=<lanade cost checkout token>
"delivery_method": "postal",	If set courier then separate  logic for Landed cost calculation will be applied.
"delivery_cost": 37.56,	Price to be provided without VAT
"delivery_address_line_1": "Ruiz #36",	Delivery address 1 line
"delivery_address_line_2": "B101",
"delivery_city": "Mexico",
"delivery_state_province": "Ciudad de",
"delivery_postal_code": "06720",
"delivery_country": "FI",
"delivery_phone": "not provided",
"delivery_email": "email@hotmail.com",
"order_breakdown": [	List of order items
{
"short_description": "Tie Dye Hoodie",
"long_description": "",	Might be empty
"id_provided_by_em": "32714384",	SKU or any other unique identifier for the product, this ID should be unique within the order.
"quantity": 1,
"weight": 1.53125,	Weight per unit to be provided in the unit of measurement set for EM in EAS system (for testing account it is kg, but can be changed on request)
"type_of_goods": "goods",	If item is electronic goods (downloadable, tickets …) then need to set TBE, otherwise GOODS If you are selling gift cars that can be used for payments in the store use GIFTCARD  Enumeration [ GOODS, TBE, GIFTCARD ]
"location_warehouse_country": "US",	ISO 2 alpha Country code of the warehouse from, goods will be dispatched (usually Merchants registration country)
"cost_provided_by_em": 45,	1 item (unit) price (VAT inclusive and Exclusive based on clients configuration). Test account usually configured as Tax exclusive prices.
"hs6p_received": "",	Harmonized system code for the product, known as HS6 code.  If provided empty, system will select it using AI.
"reduced_tbe_vat_group": false,	System can’t determine reduced VAT rate for TBE, so if reduced VAT rate to be applied, set reduced_tbe_vat_group  to true.
"act_as_disclosed_agent": false,	If this particular product belong to different seller need to set true.
"seller_registration_country": "US",	If this particular product belong to different seller need to set this sellers registration Country.
"originating_country": "US"	Country code where goods were produced (this influence on the customs duties rates)
}
]
}

 

200 OK with Call back URL with EAS JWT token or Redirection URL to the B2B confirmation page.

 

JWT Order token description

	Description
{
"delivery_charge_vat": 9.01,	See note[1]
"merchandise_cost_vat_excl": 45,	If prices are VAT inclusive this will differ from merchandise_cost  on VAT value
"merchandise_cost": 45,
"delivery_charge": 37.56,
"delivery_charge_vat_excl": 37.56,	If prices are VAT inclusive this will differ from delivery_charge on VAT value
"delivery_country": "FI",
"payment_currency": "USD",
"merchandise_vat": 10.8,	Total VAT on the goods
"eas_fee_vat": 0,
"total_order_amount": 102.37,	This total order amount to be paid by client of the store
"total_customs_duties": 0,
"eas_fee": 0,
"delivery_address": null,
"order_id": "#150097",
"items": [
{
"item_id": "32714384343086",
"quantity": 1,
"unit_cost": 45,
"unit_cost_excl_vat": 45,	If prices are VAT inclusive this will differ from unit_cost on VAT value
"item_delivery_charge": 37.56,	Part of Delivery cost Prorated by goods cos
"item_delivery_charge_vat_excl": 37.56,	If prices are VAT inclusive this will differ from item_delivery_charge_vat_excl on VAT value
"item_delivery_charge_vat": 9.01,
"item_customs_duties": 0,
"item_eas_fee": 0,
"item_eas_fee_vat": 0,
"applicable_hs6p": "621510",
"vat_rate": 24,
"item_duties_and_taxes": 19.81,	Total taxes and duties for the item, includes: item_delivery_charge_vat, item_eas_fee_vat, item_eas_fee, item_delivery_charge_vat and item_customs_duties To determine VAT for particular item need to use formula VAT for item = item_duties_and_taxes - item_customs_duties - item_delivery_charge_vat - item_eas_fee_vat - item_eas_fee
"customs_duties_rate": "0%"	This value shows applicable Customs duties rate in percent of per kg (kg)
}
],
"taxes_and_duties": 19.81,	Total taxes and duties for the goods on the order level includes: merchandise_vat, total_customs_duties, delivery_charge_vat, eas_fee_vat, eas_fee
"FID": "77e09031c9bfd3d44248601389aed110",
"id": 55019,
"timestamp_year": 2022,
"iat": 1665056443,
"exp": 4789258843,
"aud": "checkout_713",
"iss": "@eas/auth",
"sub": "checkout",
"jti": "ed46442f-0793-415d-9b2e-51c5da2409bb"
}

[1] When VAT is calculated for Delivery cost, system takes prorated part of delivery cost for the goods and applies VAT to each part, that is why VAT rate for delivery cost might be different from standard VAT rate when in one order present goods with different VAT rates.

2. Update external order number (Order number in your store) if needed

End point	/updateExternalOrderId
Authorization	Bearer Authorization token
Body	In the body to be provided checkout_token for the Order (from step 1) and real order number.

Example:

{
  "external_order_id": "Real order number from your system",
  "order_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRlZmF1bHQifQ.eyJlYXNfZmVlIjo0LCJtZXJjaGFuZGlzZV9jb3N0IjoxMDAsImRlbGl2ZXJ5X2NoYXJnZSI6MTAsIm9yZGVyX2lkIjoiYXBpX29yZGVyXzAwMTEiLCJ0YXhlc19hbmRfZHV0aWVzIjoyNy4zNiwiaWQiOjMyNiwiaWF0IjoxNjE2NTcyNDE4LCJleHAiOjE2MTY2NTg4MTgsImF1ZCI6ImNoZWNrb3V0XzMiLCJpc3MiOiJAZWFzL2F1dGgiLCJzdWIiOiJjaGVja291dCIsImp0aSI6IjFmZmNlNDVlLThiYTktNGEwMi05N2NmLTViNTQ2ZGMyM2FjOSJ9.vFtHaDePrZqsMbjWNL71nRlW7cX8De_dAtt1MIJRv1PETbyUSaodyXe_F2qxjpcKc0aOT7qXe5HjTwCGhXwG8w"
}

3. Update payment status of the order

End point	/payment/verify
Authorization	Bearer Authorization token
Body	In the body to be provided checkout_token for the Order (from step 1)  and checkout_payment_id Checkout_payment_id not validated and stored for information purposes only.

Example:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRlZmF1bHQifQ.eyJlYXNfZmVlIjo0LCJtZXJjaGFuZGlzZV9jb3N0IjoxMDAsImRlbGl2ZXJ5X2NoYXJnZSI6MTAsIm9yZGVyX2lkIjoiYXBpX29yZGVyXzAwMTEiLCJ0YXhlc19hbmRfZHV0aWVzIjoyNy4zNiwiaWQiOjMyNiwiaWF0IjoxNjE2NTcyNDE4LCJleHAiOjE2MTY2NTg4MTgsImF1ZCI6ImNoZWNrb3V0XzMiLCJpc3MiOiJAZWFzL2F1dGgiLCJzdWIiOiJjaGVja291dCIsImp0aSI6IjFmZmNlNDVlLThiYTktNGEwMi05N2NmLTViNTQ2ZGMyM2FjOSJ9.vFtHaDePrZqsMbjWNL71nRlW7cX8De_dAtt1MIJRv1PETbyUSaodyXe_F2qxjpcKc0aOT7qXe5HjTwCGhXwG8w",
  "checkout_payment_id": "payment_token_from_payment_gateway"
}

 

Creating shipment

When order is shipped to the customer, need to provide to EAS system tracking number for the shipment. Using this tracking number EAS system will create Shipment for the order and generate CN22/23, QR code, Customs declaration in the XML format.

End point	/shipment/create_shipment
Authorization	Bearer Authorization token
Body	In the body to be provided checkout_token for the Order (from step 1) and s10_code – tracking number

Example:

{
  "s10_code": "EE221002830FI",
  "order_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRlZmF1bHQifQ.eyJlYXNfZmVlIjo0LCJtZXJjaGFuZGlzZV9jb3N0IjoxMDAsImRlbGl2ZXJ5X2NoYXJnZSI6MTAsIm9yZGVyX2lkIjoiYXBpX29yZGVyXzAwMTEiLCJ0YXhlc19hbmRfZHV0aWVzIjoyNy4zNiwiaWQiOjMyNiwiaWF0IjoxNjE2NTcyNDE4LCJleHAiOjE2MTY2NTg4MTgsImF1ZCI6ImNoZWNrb3V0XzMiLCJpc3MiOiJAZWFzL2F1dGgiLCJzdWIiOiJjaGVja291dCIsImp0aSI6IjFmZmNlNDVlLThiYTktNGEwMi05N2NmLTViNTQ2ZGMyM2FjOSJ9.vFtHaDePrZqsMbjWNL71nRlW7cX8De_dAtt1MIJRv1PETbyUSaodyXe_F2qxjpcKc0aOT7qXe5HjTwCGhXwG8w
}