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/ |
Credentials for Production environment to be requested separately from EAS Project support team.
Authorization
EAS REST API uses oAuth 2.0
| Authorization end point |
/auth/open-id/connect |
| Method |
POST |
| Request BODY |
grant_type: "client_credentials"
scope: "openid" client_id: "Use API Key from the Dashboard General section" client_secret: "use API Secret from Dashbaord General Settings" |
| 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 |
| Headers | |
| 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 |
| "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) |
| } | |
| ] | |
| } |
Please keep in mind that if Harmonised system code for the product not provided it will take time for AI to identify HS code and based on it VAT rate (In production environment it is approx. 600 msec. per item)
200 OK with Call back URL with EAS JWT token or Redirection URL to the B2B confirmation page.
JWT Order token description
JWT token can be decoded using https://jwt.io/libraries
| 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.
To validate JWT token you can use EAS public key retrieved via method /auth/keys
2. Update external order number (Order number in your store) if needed
| End point |
/updateExternalOrderId |
| Headers | |
| 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 |
| Headers | |
| 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"
}
Optional step: Creating shipment
When order is shipped to the customer, you may 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.
This step might be skipped.
| End point |
/shipment/create_shipment |
| Headers | |
| 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
}
For more information, contact us at support@easproject.com