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

Transactions

Each sale in Taxamo is represented as a transaction. Transactions have several possible statuses but typically they are stored initially with a status of N (new / unconfirmed) prior to processing the customer’s payment; once the payment has processed the status is updated to C (confirmed). Only confirmed transactions appear in the various reports.

The transaction contains all of the sale’s information, primarily:

  • Sale order lines, with amounts, descriptions, etc.
  • Currency information
  • Tax-related information - location evidence, tax region/country assigned, tax rates
  • Buyer information, including the billing address and email address
  • A number of custom fields, able to carry additional information
  • Invoice image reference
  • Issued refunds
  • Registered payments

There are several types of transactions:

  • Merchant - standard transactions in which Taxamo is not an intermediary
  • Taxamo - standard transactions in which Taxamo was an intermediary
  • Self-billed - for transactions in which Taxamo was an intermediary and additional transaction is automatically created in the system from the merchant to Taxamo
  • Placeholder - when a sale is made for a subscription product a placeholder transaction can be created to store the location evidence, which future renewals will reference.

Tax region

A tax region is a country, or group of countries, that have a common reporting target - for example the 28 member countries of the European Union, or the Switzerland region which also includes Liechtenstein.

Upon processing a sale Taxamo will assign an appropriate region and country to the transaction, so that the sale complies with the appropriate tax laws.

The tax region can be either:

  • Delegated for Taxamo to be the seller: Transactions made in this region will have the VAT/GST obligation taken over by Taxamo.
  • Enabled for tax and the merchant is the seller: In this case the relevant tax region laws are adhered to and, in default configuration, the tax is applied. For such regions, it is possible to browse tax reports generated by Taxamo and use them for filing directly with the relevant tax authority.
  • Disabled for tax: transactions for this region will be stored, but tax will not be calculated and applied and Taxamo will not provide tax reports.

In addition, if there is any region that you do not want to sell to, it can be blocked so that sales to that region will not proceed.

Test mode

Test mode is the default mode of operation for every newly-created Taxamo account. Test mode allows merchants to familiarise themselves with the service in ‘sandbox’ mode.

Merchants can perform the same operations in test mode as in live mode, such as:

  • Login to the Taxamo Merchant Portal
  • Use the Checkout Form or JavaScript API or REST API to:
    • Test transaction flow
    • Browse reports and transactions for test data
    • Integrate with Payment Gateways in test/sandbox mode

Transactions performed using test mode tokens are stored within Taxamo, but are not settled with tax authorities.

Merchants can perform as many transactions as required while in test mode in order to fully evaluate the Taxamo platform.

Live mode

Live mode is used for processing actual sales. This mode will connect to payment providers in live/production mode. For sales where the VAT/GST obligation is delegated to Taxamo, the tax will be settled with the relevant tax authorities.

Even with live mode enabled, merchants still have access to both sets of tokens. Depending on the token used, any incoming data will be applied to the appropriate mode.

Concepts


Suggested Edits are limited on API Reference Pages

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