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

Direct Integration Overview

Taxamo's RESTful API is available for merchants that want to integrate Taxamo into their checkout process while maintaining complete control over the sequence of calls and the payment methods used.

In addition, merchants that use the Taxamo checkout form may also want to use various endpoints in our API to access any stored data.

Taxamo must enable access to the API on each account - please reach out to us at support@taxamo.com to enable it.

Basic process

Integration with the API generally follows a sequence like this:

Notes:

  1. It is necessary to handle response codes from the Taxamo API and display the correct information to the customer.
  2. For the Intermediary service, it is required to display a "Taxamo" logo/label near/upon the checkout "Proceed" button for transactions in which Taxamo assumes the VAT/GST liability for the transaction.
  3. Taxamo's Invoicing Overview enables merchants to send payment receipt invoices to their customers for confirmed transactions.
  4. All communication is implemented on the server-side, by invoking the Taxamo API with your private token.

1. Displaying the checkout page

Initially, the customer browses through the merchant's e-commerce site as usual.

Upon proceeding to the Checkout page, the e-commerce site contacts the Taxamo API to get information on tax rates and the tax delegation by invoking the POST /api/v2/tax/calculate endpoint.

Information returned from this call should be used to display the relevant tax information and to decide if the Taxamo logo/label is to be shown or not.

The most important attributes, in addition to the transaction fields described below, are:

  • tax_required_fields - a list of fields that are required for the tax calculation. For example, Canada requires a 2-letter province code while the United States needs an entire address, including a state code and a zip code.
  • storage_required_fields - additional fields might be required for issuing a correct invoice, or for audit purposes. In practice, all fields listed here should be requested from the customer. Taxamo will check required fields for all delegated transactions - if you wish to check them on your sales as well, pass force_storage_fields_check field in the request and set it to true.
  • is_delegated - if true the Taxamo logo (available here) must be displayed. This transaction will have the VAT/GST obligation assumed by Taxamo.
  • error_code - if present this means that an additional action needs to be performed. Depending on the value of this attribute the action can be:
    • missing_tax_required_fields - not all fields indicated in tax_required_fields were given.
    • missing_storage_required_fields - not all fields indicated in storage_required_fields were given.
    • no_matching_evidence - the API was not able to establish a valid tax location. Check the transaction.evidence attribute in response for countries detected.
    • validation_error - a separate validation error, for example no currency_code provided. Consult the errors array in the response for more details.

2. Capturing the transaction

Once the customer accepts the order and provides their payment details, Taxamo needs to be notified of the order
by invoking the POST /api/v2/transactions endpoint.

This operation returns information on whether the payment can be captured or not. It also returns a unique transaction key that has to be
referenced in step 3 below.

The response attributes listed in step 1 should be taken into account when checking the response from transaction storage.

Notes:

  1. This step should be performed for all sales. If the VAT/GST obligation is not with Taxamo then your software can proceed with the payment without checking the payment acceptance from Taxamo.
  2. Where the transaction is to be delegated to Taxamo, the Taxamo logo should appear on the checkout page prior to confirmation of the transaction.

3. Confirming the transaction

If the payment has been captured successfully then Taxamo must be notified of this by your software for each sale.
This operation can occur outside of the regular payment flow, but you should note that the transaction will remain as unconfirmed and no Taxamo invoice will be available prior to this step being carried out.

It is possible for Taxamo to receive this notification from the PSP for the specific PSPs that provide webhooks that we support. Otherwise the merchant service must make the call to provide this notification.

The confirmation of non-delegated transactions enables detailed reporting on these sales in Taxamo.

To confirm the transaction the POST /api/v2/transactions/:key/confirm
endpoint has to be used.

4. Unsuccessful transaction

If the transaction was not successful then instead of confirming the transaction it should be cancelled by invoking the
DELETE /api/v2/transactions/:key
endpoint.

In this case, no invoice will be issued for this transaction.

API communication

Please note that it is necessary to use the Taxamo API v2 endpoint. If upgrading from the v1 API or referencing older documentation, https://api.taxamo.com/ must be replaced with https://services.taxamo.com in the request URLs.

Direct Integration Overview


Suggested Edits are limited on API Reference Pages

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