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 firstname.lastname@example.org to enable it.
Integration with the API generally follows a sequence like this:
- It is necessary to handle response codes from the Taxamo API and display the correct information to the customer.
- 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.
- Taxamo's Invoicing Overview enables merchants to send payment receipt invoices to their customers for confirmed transactions.
- All communication is implemented on the server-side, by invoking the Taxamo API with your private token.
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_checkfield in the request and set it to
truethe 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
missing_storage_required_fields- not all fields indicated in
no_matching_evidence- the API was not able to establish a valid tax location. Check the
transaction.evidenceattribute in response for countries detected.
validation_error- a separate validation error, for example no
currency_codeprovided. Consult the
errorsarray in the response for more details.
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.
- 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.
- Where the transaction is to be delegated to Taxamo, the Taxamo logo should appear on the checkout page prior to confirmation of 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
endpoint has to be used.
If the transaction was not successful then instead of confirming the transaction it should be cancelled by invoking the
In this case, no invoice will be issued for this transaction.