JavaScript API
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)
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>
Updated almost 2 years ago