uStore provides the out-of-the-box tax calculator, which is suitable for simple taxation use cases.
When the taxation is more complex, you can integrate an external tax service using the tax webhook.
The webhook gets the order data and returns the correct tax.

Eligible customers can contact XMPie Support, and receive the Tax webhook sample application and its documentation.

The following activity diagram shows uStore's communication with the tax webhook.

uStore sends data to the webhook from the stored procedure in JSON format, in the body of the HTTP POST request.
The request should have the following headers:

• Content-Type: application/json
• X-Signature: hashing of the request body (the body needs to be hashed with the signatureKey using SHA-512 algorithm)

If you have discount information for the order, it is added to the body of the request as follows:

"DiscountInfo": {
  "Items": [
    {
      "OrderProductId": 136,
      "Discount": 1.25,
      "DiscountForSubtotal": 1.25,
      "DiscountForRL": 0.0
    },
    {
      "OrderProductId": 137,
      "Discount": 1.75,
      "DiscountForSubtotal": 1.75,
      "DiscountForRL": 0.0
    }
  ],
  "Discount": 3.0,
  "CouponCode": "1A345QTD"
}

Explanation of the properties:

• DiscountInfo > items > Discount: the total discount for this order product (DiscountForSubtotal + DiscountForRL).
• DiscountInfo > items > DiscountForSubtotal: the discount for the specific order product considering the requested quantity.
• DiscountInfo > items > DiscountForRL: if there is any charge for recipient list, then this is the discount amount applied for this charge.
• DiscountInfo > Discount: total discount for this order.
• DiscountInfo > CouponCode: the coupon code used by the shopper during checkout.

The webhook returns data with tax and optional extra data in JSON format.
The response should have the following headers:

• Content-Type: application/json
• X-Signature: hashing of the response body (the body needs to be hashed with the signatureKey using SHA-512 algorithm)

Description of a response body

{
    "TotalTax": <number>,
    "Taxes": [
        {
            "Name": <string>,
            "DisplayName": <string>,
            "Percentage": <number>,
            "TaxID": <number>,
            "TaxAmount": <number>
        }
    ],
    "TaxItems": [
        {
            "OrderItemID": <number>,
            "OrderItemTaxes": [
                {
                    "TaxID": <number>,
                    "TaxAmount": <number>
                }
            ],
            "TaxAmount": <number>
        }
    ]
}

Example of a response body

{
    "TotalTax": 6.550000,
    "Taxes": [
        {
            "Name": "UsTax",
            "DisplayName": "Display_UsTax",
            "Percentage": 50.0,
            "TaxID": 10001,
            "TaxAmount": 5.275000
        },
        {
            "Name": "TaxWebhookTG",
            "DisplayName": "Display_TaxWebhookTG",
            "Percentage": 50.0,
            "TaxID": 10002,
            "TaxAmount": 1.275000
        }
    ],
    "TaxItems": [
        {
            "OrderItemID": 22600,
            "OrderItemTaxes": [
                {
                    "TaxID": 10001,
                    "TaxAmount": 5.275000
                }
            ],
            "TaxAmount": 5.275000
        },
        {
            "OrderItemID": 22601,
            "OrderItemTaxes": [
                {
                    "TaxID": 10002,
                    "TaxAmount": 1.275000
                }
            ],
            "TaxAmount": 1.275000
        }
    ]
}

Error messages can be propagated from the tax service or the webhook back to uStore.
You should return in the response a status code 400 (BadRequest) and pass the error message in the body as follows:

{ 
    "message": "...error message text..." 
} 

uStore hashes the body of the request and sends it in the X-Signature header, and expects the webhook to do the same for the body of the response.
The hashing is done with the signatureKey using SHA-512 algorithm.