Get transaction data via the Taxamo API

Assure

For sales in which Taxamo is an intermediary, transaction data for the sale to the customer is stored in Taxamo's Assure (intermediary) account, not in your merchant account.

In these instances your merchant account will get a corresponding transaction reflecting the invoice between you and Taxamo (the back-to-back invoice).

• If the transaction key references a sale between the customer and Taxamo, which is stored with Taxamo's Assure account, fetch its data and return it.
• If the transaction key references a sale between the merchant account and Taxamo, fetch both transactions. Return the customer/Taxamo sale data as primary, and return the transaction between the merchant account and Taxamo under the transaction.back_to_back_transaction field.

Advantage

The transaction data endpoint follows this logic:

• Determine the type of transaction
• If the transaction key references a sale between the customer and the merchant, return transaction data as usual.

Recognizing transactions

Even though there is logic that distinguishes between the types of transactions already in the merchant portal and in the Taxamo API, it is helpful to recognize these transactions in the merchant software directly.

This recognition can be useful in edge use-cases, or for debugging purposes.

Sales between the customer and Taxamo

Sales between customers and Taxamo are registered in the Taxamo merchant account. The payment is registered in your PSP account as usual, with an application fee covering the VAT/GST and Taxamo's commission.

In Taxamo, such sales will have the transaction.sub_account_id field set to a non-empty value.

In Stripe, such charges will have the application_fee field set to a non-0 value. The Stripe charge will always reference the actual Taxamo transaction through metadata.taxamo_key, so it might be more useful to just use this field value to get the transaction data when a notification is received.

In the case of Stripe subscriptions, the charges are created by the Stripe scheduler, and Taxamo will update the charges on receipt of the invoice.payment_succeeded event.

A split-payment transaction will be created for the tax and the Taxamo commission amount.

This transaction can be subscribed to in Taxamo's webhooks as usual and will be included in the Taxamo API listTransactions API call results.

Note: In the case of subscriptions for sales between your customer and Taxamo, the zero-amount placeholder transaction with evidence and customer data is held on Taxamo's account.

Back-to-back sales between Taxamo and the merchant

Assure

For each sale between your customer and Taxamo, an additional transaction between Taxamo and merchant will be created and confirmed.

This transaction will not appear as a charge, but will meet the following characteristics:

• It will have its custom_id field set to an actual sale transaction key.
• It will have the parent-transaction-tax-country, parent-transaction-kind, parent-transaction-tax-amount, parent-transaction-total-amount, parent-transaction-tax-deducted, parent-transaction-amount custom fields filled out with information about the actual sale (parent) transaction.

This transaction can be subscribed to via a Taxamo webhook and will be included in the Taxamo API listTransactions call result.

Regular sales between a customer and the merchant

Advantage

If the transaction does not meet any of the above criteria, it is treated as an regular transaction that is carried out directly between the merchant and the customer.

Transactions search

The Taxamo API endpoint listTransactions() - GET /api/v2/transactions will list both the back-to-back and customer sales. All of the records can be filtered using transaction criteria as with the regular API.

Fetching enhanced transaction data

There is an additional endpoint for fetching enhanced transaction data - GET /api/v2/transactions/:key/full. This endpoint will work for regular sales, delegated sales, and back-to-back transactions. It will also fill out two additional lists:

• payments for registered payments
• refunds for registered refunds