Read about the various elements of the JavaScript API.

Setup

The following script is used for setting up:

<script src="https://services.taxamo.com/js/dropinui.js"></script>

Initialization

The following components are used during initialization:

Constructor

The constructor is used to lookup a current tax result. It uses the following format:

TaxamoDropInUI(transactionData, options)

The following table lists the available parameters:

The following table lists the available configuration options:

This function creates a Drop-In UI object that is attached to transactionData.

// Set up the Drop-In UI object
var ui = TaxamoDropInUI(transactionData, {
  uriPrefix: "https://services.taxamo.com",
  debug: true,
  public_token: "public_test_...",
  updateElementsFromTransaction: true
});

scanDataAttributes

The scanDataAttributes() component is used to enable the use of data-taxamo* attributes. For more information, see Data Attributes.

For example:

ui.scanDataAttributes();

Tax Calculation

The following components are used for tax calculations.

calculateTax

The calculateTax() component triggers tax calculation and returns a promise which can be dereferenced to obtain the response data.

For example:

ui.calculateTax();

getTaxResult

The getTaxResult() component returns current tax result information. The result is the same as the response from the Calculate tax API endpoint.

For example:

ui.getTaxResult();

// Get the total amount to collect for payment
ui.getTaxResult().transaction.total_amount;

getTaxResultFieldValueFn

The getTaxResultFieldValueFn(field) component returns the tax result field value from the current tax result. It can use the dot syntax to access nested values.

The following table lists the parameter for this component:

For example:

ui.attachDisplay(document.getElementById("tax-wrapper"),
                 ui.getTaxResultFieldValueFn("transaction.tax_supported"));

Utilities

The following components provide various utilities.

## isFieldTaxRequiredFn

The isFieldTaxRequiredFn(field) component returns a 0-arg function that will return true if the field is required for tax calculation for the current tax result. This uses the tax-required-fields field in the response.

The following table lists the parameter for this component:

For example:

ui.attachDisplay(document.getElementById("taxamo-postal-code-wrapper"), 
                 ui.isFieldTaxRequiredFn("invoice_address.postal_code"));

isFieldStorageRequiredFn

The isFieldStorageRequiredFn(field) component returns a 0-arg function that will return true if the field is required for storage for the current tax result. This uses the storage-required-fields field in the response.

The following table lists the parameter for this component:

For example:

ui.attachDisplay(document.getElementById("taxamo-postal-code-wrapper"), 
                 ui.isFieldStorageRequiredFn("invoice_address.postal_code"));

Behavior

The following components control how the integration works.

attachAmountLineLabel

The attachAmountLineLabel(elementToBind, lineCustomId, fieldName, formatter) component binds the contents of the element to a field from transaction line with a given custom ID from the tax result and formats it as a currency amount.

The following table lists the available parameters:

For example:

ui.attachAmountLineLabel(document.getElementById("line-1-total-amount-label"), "1", "total_amount", "decimal-comma");

attachAmountTransactionLabel

The attachAmountTransactionLabel(elementToBind, fieldName, formatter) component binds the contents of the element to a field from the transaction from the tax result and formats it as a currency amount.

The following parameters are available:

For example:

ui.attachAmountTransactionLabel(document.getElementById("total-amount-label"), "total_amount", "decimal-comma");

attachBillingCountry(elementToBind)

The attachBillingCountry(elementToBind) component attaches billing country logic and populates the list of countries for this element, assuming that it is a SELECT element.

The following parameter is available:

📘

Information

When the billing country is not yet set in the transaction data, it will be guessed from the IP address geolocation.

attachBuyerTaxNumberStatusLabels

The attachBuyerTaxNumberStatusLabels(successLabelEl, failureLabelEl, errorLabelEl, taxAppliedLabelEl) component attaches the logic for hiding and showing buyer tax number validation status labels.

The following parameters are available:

For example:

ui.attachBuyerTaxNumberStatusLabels(
  document.getElementById("taxamo-buyer-tax-number-valid"),
  document.getElementById("taxamo-buyer-tax-number-invalid"),
  document.getElementById("taxamo-buyer-tax-number-error"),
  document.getElementById("taxamo-buyer-tax-number-vat-applied"));

attachDisplay

attachDisplay(elementToBind, checkFn)

Parameters:
elementToBind - HTML element to bind to
checkFn - a 0-arg function which returns true/false

Checks if the provided checkFn returns true. If yes, sets the element.style.display to "", otherwise, sets the element.style.display to "none", hiding the element.

Can be combined with getTaxResultFieldValueFn to show elements depending on a field in the tax calculation response, for example.

ui.attachDisplay(document.getElementById("tax-wrapper"),                       
                 ui.getTaxResultFieldValueFn("transaction.tax_supported"));

attachLabel

attachLabel(elementToBind, field)

Parameters:
elementToBind - HTML element to bind to
field - field to lookup in the current tax result

Bind the contents of the element to a field name from the tax result.

ui.attachLabel(document.getElementById("buyer-tax-number-captcha-prompt"), "transaction.additional_interactions.b2b_captcha.interaction_prompt_message");

attachLineLabel

attachLineLabel(elementToBind, lineCustomId, fieldName)

Parameters:
elementToBind - HTML element to bind to
lineCustomId - custom_id for the Taxamo transaction line item to use
fieldName - amount field from the chosen line item to use, e.g. "total_amount"

Binds the contents of the element to a field from transaction line with a given custom_id from the current tax result.

ui.attachLineLabel(document.getElementById("tax-name-label"), "1", "tax_name");

attachLoading

attachLoading(elementToBind)

Parameters:
elementToBind - HTML element to bind to

Shows the element when tax calculation request is being processed, hides when it finishes.

attachRegionWidget

attachRegionWidget()

Please see the region component description for details.

attachTaxamoLogo

attachTaxamoLogo(elementToBind)

Parameters:
elementToBind - HTML element to bind to

Fills the element with an IMG tag containing Taxamo logo when the transaction is delegated to Taxamo for the Taxamo Assure solution.

attachBuyerTaxNumberWidget

attachBuyerTaxNumberWidget()

Please see the Components description for details.

bindFieldToElement

bindFieldToElement(elementToBind, field, opts)

Parameters:
elementToBind - HTML element to bind to
field - field to lookup in the current tax result
opts - map of options

Options:
requiredLevel - set to "always" to override the default
debounce - number of milliseconds between

Two-way binds the provided element to a tax calculation request field. It will also manage the required attribute based on tax-required-fields and storage-required-fields from the response data.

See Direct Integration Overview for information on the response fields.

ui.bindFieldToElement(document.getElementById("taxamo-buyer-email"), "buyer_email", {requiredLevel: "always"}); // always required

ui.bindFieldToElement(document.getElementById("taxamo-buyer-tax-number"), "buyer_tax_number", {debounce: 1000}); // to not trigger too many tax calculations

updateTransactionFieldValue

updateTransactionFieldValue(field, value)

Parameters:
field - field to update in the transaction
value - new value for the field

Updates the transaction data linked to the Drop-In UI component.

If the value was changed a tax calculation is triggered if:

• the field is required for tax calculation or storage
  or
• a trigger function is present for the field and returns true

If updateElementsFromTransaction is true in the component options (see Constructor) the value of element bound to the field (if any) is also updated.

CAPTCHA

attachCaptchaCheckResultStatusLabels

attachCaptchaCheckResultStatusLabels(checkFailedLabelEl, refreshLabelEl)

Parameters:
checkFailedLabel - HTML element to show when transaction.additional_interactions.b2b_captcha.captcha.check_result is "invalid"
refreshLabel - HTML element to show when transaction.additional_interactions.b2b_captcha.captcha.check_result is "expired"

Attaches the logic for hiding and showing captcha status labels.

attachCaptchaImage

attachCaptchaImage(elementToBind)

Parameters:
elementToBind - HTML element to bind to

Attach captcha image logic to the provided element, which should be an IMG.

reloadCaptchaImage

reloadCaptchaImage()

Triggers tax calculation for a captcha image refresh. Can be bound to a button for example:

<button class="btn btn-default pull-right" onclick="ui.reloadCaptchaImage()">Reload</button>

submitCaptchaSolution

submitCaptchaSolution(solution)

Parameters:
solution - CAPTCHA solution text

Submits the captcha solution to validate the tax number via tax calculation endpoint.

🚧

Please note, that some tax authorities won't return information on whether the captcha or the number are incorrect.

<button class="btn btn-default" id="captcha-submit-button"
        onclick="ui.submitCaptchaSolution(document.getElementById('captcha-solution').value);">Submit</button>