JavaScript API
To add support for the service's API to a website, just place the following HTML code anywhere inside the <html> tag:
<script type="text/javascript" src="https://api.taxamo.com/js/v1/taxamo.all.js"></script>
It is also possible to use the service without jQuery. For example, if the website already loads jQuery:
<script type="text/javascript" src="https://api.taxamo.com/js/v1/taxamo.all.nojquery.js">
</script>
Next, run the Taxamo.initialize(publicToken) function with a 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
Note
Remember to replace
SamplePublicTestKey1with your public token. Visit the JavaScript API page on the Merchant Portal to view the relevant JavaScript code snippet with your public token already placed in it.
Launching
The 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 Checkout Form= and launch them as buttons or links by simply copying and pasting the HTML code.
For more examples, see One-time Sales and Subscriptions.
Note
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
transactionThe first argument represents a transaction object. Refer to the Taxamo API documentation for more details. The most important fields are mentioned below.
| Field | Type | Description |
|---|---|---|
| currency_code (required for one-time sales) | string | 3-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) | string | Unique line identifier provided on input. |
| transaction_lines/description | string | Transaction line description. |
| transaction_lines/product_type | string | Transaction line product type. |
transaction_lines/amount (either amount or total_amount or unit_price is required) | numeric | Line amount without tax. |
transaction_lines/total_amount (either amount or total_amount or unit_price is required) | numeric | Line total amount including tax. |
transaction_lines/unit_price (either amount or total_amount or unit_price is required) | numeric | Line item unit price without tax. |
| transaction_lines/quantity | numeric | Line item quantity. Defaults to 1. |
| billing_country_code | string | A 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_name | string | Buyer name. |
| buyer_email | string | Buyer email. Can be used to deliver the invoice generated by Taxamo. |
| buyer_tax_number | string | Buyer tax number, for example an EU VAT number. |
| invoice_address | Object | Invoice 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_id | string | Custom ID that can be provided by your software, and used as a reference later. |
| customer_id | string | Free-form field for storing customer ID. |
| custom_data | string | Custom data related to the transaction. |
| description | string | Transaction description. |
| custom_fields | Object[] | 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: '...'}] | string | For 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: '...'}] | string | For 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: '...'}] | string | For subscription mode with Stripe, it is possible to enable coupons and provide the coupon code up-front. |
metadata
metadataThe 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.*
| Field | Type | Description |
|---|---|---|
| allowed_payment_providers | string | Comma-separated list of payment providers, e.g. stripe,paypal. If not provided, all of the configured payment providers will be available. |
| default_payment_provider | string | The default payment provider. If not provided, then the first payment provider from the allowed_payment_providers list will be used. |
| finished_redirect_url | string | When 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_url | string | When 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_message | string | Finished message to be displayed upon successful purchase/subscription launch. |
| show_invoice_address | boolean | If true then the invoice address will be shown. |
| require_invoice_address | boolean | If true the invoice address will be shown and required. |
| show_buyer_name | boolean | If true the buyer name field will be shown. |
| require_buyer_name | boolean | If true the buyer name will have to be provided. |
| ask_for_cardholder_name | boolean | If 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_email | boolean | If true the buyer email field will be shown. |
| require_email | boolean | If true the buyer email will have to be provided. |
| show_summary | boolean | If 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_logo | boolean | If true the certificate provider logo will be shown in the bottom left corner of the form. Default is false. |
| show_payment_provider_logo | boolean | If true the payment provider logo will be shown in the bottom left corner of the form. Default is false. |
| show_cc_provider_logo | boolean | If 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
| Field | Type | Description |
|---|---|---|
| additional_lines[stripe,paypal] | Object | For 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].enabled | string | If 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].amount | float | Additional line amount. |
| additional_lines[stripe,paypal].total_amount | float | Additional line total amount - will override the amount field for this line. |
| additional_lines[stripe,paypal].description | string | Additional line description. Defaults to 'Processing fee'. |
Subscription mode fields
| Field | Type | Description |
|---|---|---|
| subscription_mode | boolean | Launch the form in subscription mode. This mode requires plan information to be provided. See below for details. |
| plans | Object | Subscription B2C/B2B plan information for Stripe. |
| plans/b2c_plan_id | string | B2C 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_id | string | B2B 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_view | boolean | If 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_field | boolean | If 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_deductedflag 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:
| Field | Type | Description |
|---|---|---|
| success | boolean | was operation successful |
| payment_result | object | result (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_type | string | fixed value window_closed |
| keep_socket_open | boolean | fixed 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:
-
use Taxamo Products feature which generates links for running checkout
-
generate link by providing transaction and metadata parameters to https://p.taxamo.com/checkout/api/v1/state/initialize.
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
transactionandmetadata, 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 over 2 years ago