Setup

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

Initialisation

Constructor

TaxamoDropInUI(transactionData, options)

Parameters:
transactionData - field to lookup in the current tax result
options - configuration options for the Drop-In UI component

Options:
uriPrefix - Usually "https://services.taxamo.com"
public_token - Taxamo public token
updateElementsFromTransaction - Whether to update form elements when the transaction is updated using updateTransactionFieldValue
debug - Whether to log debug messages to the console

Creates a Drop-In UI object 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

scanDataAttributes()

Enables the use of data-taxamo* attributes described in Data Attributes .

ui.scanDataAttributes();

Tax Calculation

calculateTax

calculateTax()

Triggers tax calculation, returns a promise which can be dereferenced to obtain the response data.

ui.calculateTax();

getTaxResult

getTaxResult()

Return current tax result information. The result is the response from the Calculate tax API endpoint.

ui.getTaxResult();

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

getTaxResultFieldValueFn

getTaxResultFieldValueFn(field)

Parameters:
field - field to lookup in the current tax result

Returns tax result field value from the current tax result. Can use the dot syntax to access nested values.

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

Utilities

isFieldTaxRequiredFn

isFieldTaxRequiredFn(field)

Parameters:
field - field to lookup in the current tax result

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.
See Direct Integration Overview for information on the response fields.

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

isFieldStorageRequiredFn

isFieldStorageRequiredFn(field)

Parameters:
field - field to lookup in the current tax result

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.
See Direct Integration Overview for information on key response fields.

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

Behaviour

attachAmountLineLabel

attachAmountLineLabel(elementToBind, lineCustomId, fieldName, formatter)

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"
formatter - (optional) "decimal-comma" or a function of (amount, currencyExponent, currencyCode)

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.

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

attachAmountTransactionLabel

attachAmountTransactionLabel(elementToBind, fieldName, formatter)

Parameters:
elementToBind - HTML element to bind to
fieldName - amount field from transaction to use, e.g. "total_amount"
formatter - (optional) "decimal-comma" or a function of (amount, currencyExponent, currencyCode)

Binds the contents of the element to a field from the transaction from the tax result and formats it as a currency amount.

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

attachBillingCountry(elementToBind)

attachBillingCountry(elementToBind)

Parameters:
elementToBind - HTML SELECT element

Attaches billing country logic and populates the list of countries for this element, assuming that it is a SELECT element.

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

attachBuyerTaxNumberStatusLabels

attachBuyerTaxNumberStatusLabels(successLabelEl, failureLabelEl, errorLabelEl, taxAppliedLabelEl)

Parameters:
successLabelEl - HTML element to show when tax number validation succeeds
failureLabelEl - HTML element to show when tax number validation fails
errorLabelEl - HTML element to show when tax number validation encounters an error
taxAppliedLabelEl - HTML element to show when tax is applied to the transaction

Attaches the logic for hiding and showing buyer tax number validation status labels.

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)

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>