Taxamo

The Taxamo Developer Hub

Welcome to the Taxamo developer hub. You'll find comprehensive guides and documentation to help you start working with Taxamo as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

JavaScript API

Usage

To add support for the Taxamo API to a website, just place the following HTML code anywhere inside the tag;

<script type="text/javascript" src="https://api.taxamo.com/js/v1/taxamo.all.js"></script>

It is also possible to use Taxamo without jQuery - for example if the website already loads jQuery anyway:

<script type="text/javascript" src="https://api.taxamo.com/js/v1/taxamo.all.nojquery.js">
</script>

Initialize

Next, the merchant needs to run the Taxamo.initialize(publicToken) function with the public test token as an argument.

//you should provide your token here
Taxamo.initialize('SamplePublicTestKey1');
Taxamo.verifyToken(function(data) {
    alert(data.tokenOK ? 'Correct token' : 'Invalid token');
});//demo only

Please remember to replace SamplePublicTestKey1 with your public token. Visit the JavaScript API page in the Taxamo Merchant Portal to view the relevant JavaScript code snippet with your public token already placed within it.

Launching

The Taxamo Checkout Form can be launched either as a redirection, or as a JavaScript overlay. Where the number of products is limited, it is also possible to configure products with the Taxamo Checkout and launch them as buttons/links by simply copying and pasting the HTML code.

See One-time Sales and Subscriptions for examples.

๐Ÿ“˜

The PayPal Express Checkout will always redirect the customer to a full page, as it is forbidden to embed the PayPal Express Checkout default form in an iFrame.

Reference

The Taxamo.Checkout object instance is always created in the same way, regardless of whether it will be used to launch as an overlay or a redirect:

new Taxamo.Checkout(transaction, metadata)

new Taxamo.Checkout(transaction, metadata)

The first argument represents a transaction object. Refer to the Taxamo API documentation for more details. The most important fields are introduced here:

transaction

The first argument represents a transaction object. Refer to the Taxamo API documentation for more details. The most important fields are mentioned below.

FieldTypeDescription
currency_code (required for one-time sales)string3-letter ISO currency_code.
transaction_lines (required for one-time sales, ignored for subscription_mode)TransactionLine[]Array of transaction lines.
transaction_lines/custom_id (required)stringUnique line identifier provided on input.
transaction_lines/descriptionstringTransaction line description.
transaction_lines/product_typestringTransaction line product type.
transaction_lines/amount (either amount or total_amount or unit_price is required)numericLine amount without tax.
transaction_lines/total_amount (either amount or total_amount or unit_price is required)numericLine total amount including tax.
transaction_lines/unit_price (either amount or total_amount or unit_price is required)numericLine item unit price without tax.
transaction_lines/quantitynumericLine item quantity. Defaults to 1.
billing_country_codestringA 2-letter ISO country code for the billing country.
Can be taken from Taxamo.defaultTransaction.billing_country_code if Taxamo.detectCountry() or Taxamo.setBillingCountry() were used.
buyer_namestringBuyer name.
buyer_emailstringBuyer email. Can be used to deliver the invoice generated by Taxamo.
buyer_tax_numberstringBuyer tax number, for example an EU VAT number.
invoice_addressObjectInvoice address. Can be used to populate the invoice generated by Taxamo without the need to capture this information from the customer on the {{< taxamoCheckoutProduct >}} form.
custom_idstringCustom ID that can be provided by your software, and used as a reference later.
customer_idstringFree-form field for storing customer ID.
custom_datastringCustom data related to the transaction.
descriptionstringTransaction description.
custom_fieldsObject[]A list of key/value objects, that can store additional merchant software information. Example value: [{key: 'taxed-plan-id', value: 'taxamo_taxed'}].
custom_fields[{key: "taxed-plan-id", value: '...'}]stringFor subscription mode with Stripe, it is possible to distinguish taxed and untaxed plans to be applied in different scenarios.
custom_fields[{key: "untaxed-plan-id", value: '...'}]stringFor subscription mode with Stripe, it is possible to distinguish taxed and untaxed plan to be applied in different scenarios.
custom_fields[{key: "taxamo-checkout-coupon-code", value: '...'}]stringFor subscription mode with Stripe, it is possible to enable coupons and provide the coupon code up-front.

metadata

The second argument represents a metadata object. This object holds additional information for the Taxamo Checkout Form's behaviour.

Some of the fields apply only in specific scenarios, for example with subscriptions.

Common fields

Note: Some of the common fields can be overwritten in the Taxamo Checkout settings. In this particular case, the JavaScript-provided value will be ignored.*

FieldTypeDescription
allowed_payment_providersstringComma-separated list of payment providers, e.g. stripe,paypal. If not provided, all of the configured payment providers will be available.
default_payment_providerstringThe default payment provider. If not provided, then the first payment provider from the allowed_payment_providers list will be used.
finished_redirect_urlstringWhen using the full-page redirect, provide the finished_redirect_url to return the customer browser back to your website. The request will include the Taxamo transaction key as a URL parameter taxamo_transaction_key
cancel_redirect_urlstringWhen a customer cancels checkout on a redirected PayPal page, this returns the customer browser back to the provided cancel url. If not provided, finished_redirect_url is used for the redirect if present.
finished_messagestringFinished message to be displayed upon successful purchase/subscription launch.
show_invoice_addressbooleanIf true then the invoice address will be shown.
require_invoice_addressbooleanIf true the invoice address will be shown and required.
show_buyer_namebooleanIf true the buyer name field will be shown.
require_buyer_namebooleanIf true the buyer name will have to be provided.
ask_for_cardholder_namebooleanIf true, and the credit card option is used, then the cardholder name field will be shown. Defaults to the buyer name if not provided. The value does not get stored on transaction, it only propagates to PSP.
show_emailbooleanIf true the buyer email field will be shown.
require_emailbooleanIf true the buyer email will have to be provided.
show_summarybooleanIf true the checkout summary section will be displayed in expanded mode on the form when launched in an overlay mode. The default is false, displaying the checkout summary as collapsed. It can be expanded with a click.
show_certificate_provider_logobooleanIf true the certificate provider logo will be shown in the bottom left corner of the form. Default is false.
show_payment_provider_logobooleanIf true the payment provider logo will be shown in the bottom left corner of the form. Default is false.
show_cc_provider_logobooleanIf false the credit card logo (Visa or MasterCard) will not be shown on the right side of card number input field. Default is true.

Non-subscription (one-time) mode fields

FieldTypeDescription
additional_lines[stripe,paypal]ObjectFor each PSP it is possible to specify an additional line amount and description to be applied when this PSP is selected.
additional_lines[stripe,paypal].enabledstringIf set to anything other than null, "false" or "0", will mark this line as enabled. Otherwise, it will disable additional line for this PSP.
additional_lines[stripe,paypal].amountfloatAdditional line amount.
additional_lines[stripe,paypal].total_amountfloatAdditional line total amount - will override the amount field for this line.
additional_lines[stripe,paypal].descriptionstringAdditional line description. Defaults to 'Processing fee'.

Subscription mode fields

FieldTypeDescription
subscription_modebooleanLaunch the form in subscription mode. This mode requires plan information to be provided. See below for details.
plansObjectSubscription B2C/B2B plan information for Stripe.
plans/b2c_plan_idstringB2C plan identifier for Stripe. Either B2C/B2B or taxed/untaxed plan has to be provided. If only one plan from the set is provided, it defaults for all situations. Taxed/untaxed plans trump the B2C/B2B plans.
plans/b2b_plan_idstringB2B plan identifier for Stripe. Either B2C/B2B or taxed/untaxed plan has to be provided. If only one plan from the set is provided, it defaults for all situations. Taxed/untaxed plans trump the B2C/B2B plans.
new_subscription_viewbooleanIf true the subscription information view will display the trial and initial fee information in a more detailed way. This option is automatically enabled if coupons support is enabled for the given Payment Service Provider.
show_coupon_fieldbooleanIf false the coupon field will not be visible, but any coupon provided through transaction.custom_fields\[key='taxamo-checkout-coupon-code'\] will be applied.

Plan selection

For subscription mode, Taxamo is distinguishing between two plans grouped in two exclusive sets:

  • Taxed/Untaxed - the taxed plan will be used if the transaction should have tax applied. For example if it is for another EU country and the EU region setting is enabled. Otherwise, the untaxed plan will be used. EU B2B transactions will also be treated as untaxed.
  • B2C/B2B - the B2B plan will be used if the transaction has the tax_deducted flag raised. For example when a correct EU VAT number is presented and the transaction country is not the same as the merchant's country.

.overlay(callback)

The .overlay() function takes an argument with a listener function, that will be invoked upon transaction end - successful or not. The first parameter passed to this listener function is the result object containing four fields:

FieldTypeDescription
successbooleanwas operation successful
payment_resultobjectresult (transaction object) of retrieving transaction operation. Note that in the case where subscription_mode is true, key is the placeholder transaction's key and transaction_lines holds items from payment transactions of the subscription.
message_typestringfixed value window_closed
keep_socket_openbooleanfixed value false

๐Ÿ“˜

Payment provider data

Payment provider data is available in the transaction's custom_fields. See Stripe custom fields for example.

Try it here (the JavaScript code below can be modified):

.redirect()

When using .redirect(), it is advised to set the finished_redirect_url attribute of the metadata argument, so that the form knows where to redirect the user back to after a successful transaction.

When redirecting to the finished_redirect_url Taxamo will add a taxamo_transaction_key URL parameter. This can be used to retrieve the full transaction details from the Taxamo Transaction API.

This will give access to payment provider details such as stripe-token stored in the transaction's custom_fields.

๐Ÿ“˜

Payment provider data

Payment provider data is available in the transaction's custom_fields. See Stripe custom fields for details.

Try it here (the JavaScript code below can be modified):

Embedded (iframe)

Once you have a link for running the checkout form, you can use it as src attribute on iframe element on your page.

To get checkout link you can:

Transaction and metadata fields are listed above. Provide them as:
transaction[TRANSACTION_FIELD_NAME]=TRANSACTION_FIELD_NAME_VALUE
meta[META_FIELD_NAME]=META_FIELD_VALUE

Note that you can use those with product link also.

Nested fields are also supported:
transaction[custom_fields][0][key]=anything&transaction[custom_fields][0][value]=123

Example of link for initializing checkout with transaction params:

curl -X GET https://p.taxamo.com/checkout/api/v1/state/initialize?public_token=your_public_token&transaction[currency_code]=EUR&transaction[transaction_lines][0][custom_id]=1&transaction[transaction_lines][0][amount]=1.99&meta[allowed_payment_providers]=stripe&meta[require_invoice_address]=true

JWT (JSON Web Tokens) with Taxamo Checkout

JSON Web Tokens is an unofficial standard for securing JSON content in a lightweight way, supported by a number of client libraries for all popular technologies.

With the Taxamo Checkout Form, it is possible to use a JSON Web Token to initialize the form. This, in conjunction with restricting free-form sales, allows the merchant to dynamically create sales for their users without the need to verify that the transaction wasnโ€™t altered in the JavaScript code.

The token should be generated server-side, as it is encrypted with a private token. Hereโ€™s some example code in Ruby (other languages should look similar as the code is really simple):

require 'jwt'

payload = {
  :transaction => {
    :currency_code => "EUR",
    :transaction_lines => [
      {
        :custom_id => "1", 
        :amount => 5, 
        :description => "Example product"}
    ]
  }, 
  :meta => {:allowed_payment_providers => "stripe"}}

#replace with your private live or test token
token = JWT.encode payload, 'SamplePrivateTestKey1', 'HS256'

The resulting token can be used in the example code below:

//you should provide your token here
Taxamo.initialize('SamplePublicTestKey1');

new Taxamo.CheckoutJWT(jwtoken, transaction, metadata);

Or in a link, such as:

curl -X GET https://p.taxamo.com/jwt/eyJ0eXA(โ€ฆ)wZSJ9fQ.?public_token=SamplePublicTestKey1&transaction[billing_country_code]=CH&meta[finished_redirect_url]=https://www.taxamo.com

Both the link and the JavaScript invocation will allow some of the transaction and metadata fields (such as the billing country code) to be provided up-front. JWT content will have higher priority though.

Taxamo Checkout Products with Taxamo.js

Taxamo.js also provides a way to launch products pre-configured in the Taxamo Merchant Portal.

The Taxamo.js invocation is very similar to new Taxamo.Checkout(transaction, metadata) as described above, with the only difference being the additional argument with the product code:

new Taxamo.Product(product_code, transaction, metadata)

๐Ÿ“˜

The product definition overrides some of the fields in transaction and metadata, such as amounts or currency code or available Payment Service Providers.

Example code

Try it here (the JavaScript code below can be modified to your liking):

Updated about a year ago


JavaScript API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.