Transactions

The /api/v1/transactions operates on the most basic resource used in taxamo - the Transaction.

  Transaction contains all the information related to the customer’s purchase, including also tax location evidence and invoicing information for audit reports.  

Fields not marked as optional or required are computed by the API.

Transaction

Field Type Description
key string Transaction unique key, generated by taxamo. Max length 64.
test boolean Was this transaction created in test mode?
manual boolean Is the transaction created manually - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. If you need API to do that when accessing the API with private token, just skip the ‘manual’ flag or use false value there and provide customer’s ip address through buyer_ip field. Manual mode is also used when using original_transaction_key field.
custom_id string (Optional) Custom identifier provided upon transaction creation. Max length 256.
original_transaction_key string (Optional) Use data and evidence from original transaction. Tax will be re-calculated, but evidence won’t be re-checked. This parameter is taken into account only when manual mode is used. Max length 64.
custom_data string (Optional) Custom data related to a transaction. Max length 256.
description string (Optional) Transaction description. Max length 512.
status string Transaction status: N - new, C - confirmed.
currency_code string (Required) International ISO currency code, e.g. USD. Length 3.
order_date date (Optional) Order date in yyyy-MM-dd format, in merchant’s timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time. When using public token, the default value is used.
confirm_timestamp timestamp Date and time of transaction confirmation.
create_timestamp timestamp Date and time of transaction creation.
buyer_ip string (Optional) IP address of the buyer in dotted decimal (IPv4) or text format (IPv6).
buyer_name string (Optional) Buyer’s name - first name and last name or company name. Max length 512.
buyer_tax_number string (Optional) Buyer’s tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly. Max length 256.
billing_country_code string (Required) Billing two letter ISO country code. Length 2.
buyer_email string (Optional) Buyer’s declared email address. Max length 256.
buyer_credit_card_prefix string (Optional) Buyer’s credit card prefix. Max length 9.
tax_timezone string Detected timezone for the transaction. Read only.
tax_country_code string Two-letter ISO country code, e.g. FR.
This code applies to detected/set country for transaction, but can be set using manual mode. Length 2.
force_country_code string (Optional) Two-letter ISO country code. Use it to force country code instead of applying detection. Only available when private token and manual mode is used. Length 2.
tax_deducted boolean True if the transaction deducted from tax and no tax is applied. Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.
tax_entity_name string To which entity is the tax due. Read only.
total_amount numeric Total amount of transaction.
amount numeric Amount of transaction without tax.
tax_amount numeric Tax amount of transaction.
deducted_tax_amount numeric How much tax has been deducted.
refunded_total_amount numeric Total amount refunded (including tax).
refunded_tax_amount numeric Refunded tax amount.
invoice_address Address (Optional) Invoice address.
invoice_number string (Optional) Invoice number. Max length 256.
invoice_place string (Optional) Invoice place of issue. Max length 256.
invoice_date date (Optional) Invoice date of issue.
invoice_image_url string Invoice image URL - provided by Taxamo. Read only.
custom_fields object (Optional) Custom fields, stored as key-value pairs.
transaction_lines Transaction line[] (Required) List of transaction lines. At least one line is required.
countries type<->Country Map of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.
tax_supported boolean Is tax calculation supported for a detected tax location?
source string Transaction source software - e.g. plugin. Max length 256.
evidence Evidence Tax country of residence evidence.
verification_token string Verification token. Max length 64.
external-key string Transaction external key. Read only
tax-data object Tax additional information - e.g. US sales tax exemption certificate data.

Transaction line

Field Type Description
id integer Automatically assigned line identifier.
custom_id string (Required) Unique (per transaction) line identifier. Max length 64.
product_type string (Optional) Line product type. If product type does not match dictionary, ‘default’ will be used.
total_amount numeric Line total amount - with tax.
amount numeric Line amount - without tax.
quantity integer Line item quantity. Defaults to 1.
unit_price numeric Line item unit price - without tax.
deducted_tax_amount numeric Amount of tax deducted for the line.
tax_rate numeric Tax rate (in %) applied to a line.
tax_amount numeric Tax amount for the line.
tax_name string Tax name for the line. Can be overwritten when informative field is true.
description string (Optional) Line description.
product_code string (Optional) Line product code. Max length 256.
unit_of_measure string (Optional) Unit of measure for the invoice line. Max length 256.
supply_date date (Optional) Date of supply.

It is required to provide one of the following (rest of them will be derived from provided value and calculated tax):

  • total_amount
  • amount
  • quantity and unit_price

Address

Field Type Description
building_number string (Optional) Building number. Max length 256.
street_name string (Optional) Street name. Max length 256.
address_detail string (Optional) Address details - for example apartament number. Max length 256.
city string (Optional) City name. Max length 256.
postal_code string (Optional) Postal code. Max length 256.
region string (Optional) Region. Max length 256.
country string (Optional) Country description. Length 2.
freeform_address string (Optional) Freeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided. Max length 256.

Address data is not validated in any way and stored only for audit reporting.

REST Endpoints

As all public taxamo APIs, the transactions API as well is built following the RESTful API principles.

 

Path Operation
POST / Create new transaction.
GET /:key Retrieve transaction details.
PUT /:key Update transaction details.
POST /:key/confirm Mark transaction as confirmed.
DELETE /:key Cancel transaction.
GET / Browse and filter transactions.

Store transaction
POST /api/v1/transactions/

Endpoint input

JSON schema
FieldTypeDescriptionRequired?
public_tokenstringPublic token.No
private_tokenstringPrivate token.No
manual_modebooleanUse manual mode, bypassing country detection. Only allowed with private token. This flag allows to use original_transaction_key fieldNo
transactionobjectTransaction.Yes
    transaction_linesTransaction lines.Yes
    currency_codestringCurrency code for transaction - e.g. EUR.Yes
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No

Endpoint output

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction dataNo
    keystringId generated by taxamo.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    transaction_linesarrayTransaction lines.No
        idnumberGenerated id.No
        line_keystringGenerated line key.No
        custom_idstringCustom id, provided by ecommerce software.No
        product_typestringProduct type, according to dictionary /dictionaries/product_types. No
        total_amountnumberTotal amount. Required if amount or both unit price and quantity are not provided.No
        informativebooleanIf the line is provided for informative purposes. Such line must have :tax-rate and optionally :tax-name - if not, API validation will fail for this line.No
        amountnumberAmount. Required if total amount or both unit price and quantity are not provided.No
        quantitynumberQuantity Defaults to 1.No
        unit_pricenumberUnit price.No
        unit_of_measurestringUnit of measure.No
        supply_datestringDate of supply in yyyy-MM-dd format.No
        descriptionstringLine contents description.No
        product_codestringInternal product code, used for invoicing for example.No
        deducted_tax_amountnumberDeducted tax amount, calculated by taxmo.No
        deducted_tax_ratenumberDeducted tax rate, calculated by taxamo.No
        refunded_total_amountnumberRefunded total amount, calculated by taxmo.No
        refunded_tax_amountnumberRefunded tax amount, calculated by taxmo.No
        tax_ratenumberTax rate, calculated by taxamo. Must be provided when informative field is true.No
        tax_namestringTax name, calculated by taxamo. Can be overwritten when informative field is true.No
        tax_amountnumberTax amount, calculated by taxamo.No
        additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
            invoiceobjectInvoicing currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
            taxobjectTax-related currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
        custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
            keystringField's key.No
            valuestringField's value.No
        product_tax_codestringExternal product tax code for a line, for example TIC in US Sales tax.No
    testbooleanWas this transaction created in test mode?No
    manualbooleanIs the transaction created manually - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. If you need API to do that when accessing the API with private token, just skip the 'manual' flag or use false value there and provide customer's ip address through buyer_ip field. Manual mode is also used when using original_transaction_key field.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    confirm_timestampstringDate and time of transaction confirmation.No
    create_timestampstringDate and time of transaction creation.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_timezonestringTimezone name for tax transaction.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    tax_entity_namestringTo which entity is the tax due.No
    tax_entity_additional_idstringTax entity additional id.No
    total_amountnumberTotal amount of transaction.No
    amountnumberAmount of transaction without tax.No
    tax_amountnumberTax amount of transaction.No
    deducted_tax_amountnumberHow much tax has been deducted.No
    refunded_total_amountnumberTotal amount refunde (including tax).No
    refunded_tax_amountnumberRefunded tax amount.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    invoice_image_urlstringInvoice image URL - provided by Taxamo.No
    fully_informativebooleanSet to true if transaction has only informative lines.No
    kindstringTransaction kind: eu-b2c, eu-b2b, domestic, untaxedNo
    tax_supportedbooleanIs tax calculation supported for a detected tax location?No
    countriesobjectMap of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.No
        by_ipobjectCountry detected by IPNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        forcedobjectCountry forced by paramtersNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_billingobjectCountry detected by billing country codeNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_ccobjectCountry detected by credit card number prefixNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tokenobjectCountry detected from SMS tokenNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        detectedobjectCountry detected from other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        self_declarationobjectSelf declared country as evidence.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    buyer_tax_number_normalizedstringBuyer's tax number - normalized form.No
    buyer_tax_number_validbooleanIf the buyer tax number has been provided and was validated successfully. Always true for domestic transactions (billing country same as merchant's country), tax number doesn't get validated in that case.No
    buyer_tax_number_format_validbooleanIf the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.No
    tax_deductedbooleanIf the transaction is in a country supported by Taxamo, but the tax is not calculated due to merchant settings or EU B2B transaction for example.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    sourcestringTransaction source software - e.g. pluginNo
    external_keystringTransaction external keyNo
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    tax_number_servicestringTax number service identifier - if available for a given region and the region is enabled.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    warningsarrayWarnings for the transaction process, usually related to contacting B2B validation service.No
        typestringType of error.No
        messagestringError detailsNo
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
tax_required_fieldsarrayFields required for tax calculation. Depends on the region/transaction type.No
    field_namestringRequired field name.No
storage_required_fieldsarrayFields required for transaction storage (can be added later - it's up to merchant software). Depends on the region/transaction type.No
    field_namestringRequired field name.No

Authentication

Private or public token is required. It can be provided as:

  • Query string parameter, for example: POST /api/v1/transactions?private_token=SamplePrivateTestKey1&...
  • As an HTTP header, such as: Public-Token: SampleTestPublicKey1
  • JSON input argument, for example: "private_token": "SamplePrivateTestKey1"

Response codes

  • 200 - Success
  • 400 - Validation failed
  • 401 - Authentication error
  • 500 - Unexpected error

Example call

$ curl -X 'POST' -H "Content-Type: application/json" -d \
 '{
      "transaction": {
          "transaction_lines": [
              {
                  "custom_id": "line1",
                  "amount": 100
              }
          ],
          "currency_code": "EUR",
          "billing_country_code": "BE",
          "buyer_credit_card_prefix": "424242424"
      },
      "public_token": "SamplePublicTestKey1"
  }' \
 https://api.taxamo.com/api/v1/transactions
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

CreateTransactionIn input = new CreateTransactionIn();
InputTransaction transaction = new InputTransaction();
transaction.setCurrencyCode("EUR");
transaction.setBillingCouCreateTransactionOutntryCode("BE");
transaction.setBuyerCreditCardPrefix("424242424");
InputTransactionLine line = new InputTransactionLine();
line.setCustomId("line1");
line.setTotalAmount(new BigDecimal("100"));
LinkedList lines = new LinkedList<InputTransactionLine>();
lines.push(line);
transaction.setTransactionLines(lines);
input.setTransaction(transaction);
CreateTransactionOut result;

try {
    result = taxamoApi.createTransaction(input);
} catch (ApiException ae) {
    // handle exception
}

Example response

{
   "tax_required_fields" : [],
   "transaction" : {
      "billing_country_code" : "BE",
      "merchant_id" : 1,
      "tax_number_service" : "vies",
      "amount" : 100,
      "buyer_ip" : "109.121.15.46",
      "tax_timezone" : "GB",
      "fully_informative" : false,
      "tax_entity_id" : 2,
      "tax_amount" : 21,
      "create_timestamp" : "2016-10-24T09:46:22Z",
      "key" : "TvNYAAAABSFKsHx6-KjhYDdhu0hQ",
      "total_amount" : 121,
      "buyer_credit_card_prefix" : "424242424",
      "transaction_lines" : [
         {
            "line_num" : 1,
            "custom_id" : "line1",
            "tax_rate" : 21,
            "quantity" : 1,
            "tax_amount" : 21,
            "line_key" : "1atQhzXRqCJ3ELhM",
            "tax_name" : "European VAT",
            "amount" : 100,
            "unit_price" : 100,
            "total_amount" : 121
         }
      ],
      "test" : true,
      "deducted_tax_amount" : 0,
      "invoice_place" : "Dublin 2, 12 St Stephens Green",
      "update_timestamp" : 1477302382785,
      "country_name" : "Belgium",
      "tax_region" : "EU",
      "countries" : {
         "by_ip" : {
            "code_long" : "SRB",
            "name" : "Serbia",
            "cca3" : "SRB",
            "codenum" : "688",
            "ccn3" : "688",
            "code" : "RS",
            "callingCode" : [
               "381"
            ],
            "cca2" : "RS",
            "currency" : [
               "RSD"
            ],
            "tax_supported" : false
         },
         "by_billing" : {
            "callingCode" : [
               "32"
            ],
            "ccn3" : "056",
            "code" : "BE",
            "codenum" : "056",
            "tax_number_country_code" : "BE",
            "cca3" : "BEL",
            "name" : "Belgium",
            "code_long" : "BEL",
            "tax_supported" : true,
            "tax_region" : "EU",
            "currency" : [
               "EUR"
            ],
            "cca2" : "BE"
         },
         "by_payment_method" : {
            "name" : "Belgium",
            "code_long" : "BEL",
            "tax_number_country_code" : "BE",
            "cca3" : "BEL",
            "codenum" : "056",
            "callingCode" : [
               "32"
            ],
            "ccn3" : "056",
            "code" : "BE",
            "cca2" : "BE",
            "currency" : [
               "EUR"
            ],
            "tax_region" : "EU",
            "tax_supported" : true
         },
         "by_cc" : {
            "tax_supported" : true,
            "currency" : [
               "EUR"
            ],
            "tax_region" : "EU",
            "cca2" : "BE",
            "ccn3" : "056",
            "code" : "BE",
            "callingCode" : [
               "32"
            ],
            "codenum" : "056",
            "cca3" : "BEL",
            "tax_number_country_code" : "BE",
            "code_long" : "BEL",
            "name" : "Belgium"
         },
         "detected" : {
            "name" : "Belgium",
            "code_long" : "BEL",
            "tax_number_country_code" : "BE",
            "cca3" : "BEL",
            "codenum" : "056",
            "callingCode" : [
               "32"
            ],
            "code" : "BE",
            "ccn3" : "056",
            "cca2" : "BE",
            "currency" : [
               "EUR"
            ],
            "tax_region" : "EU",
            "tax_supported" : true
         }
      },
      "tax_supported" : true,
      "currency_code" : "EUR",
      "tax_country_code" : "BE",
      "order_date" : "2016-10-24T10:46:22Z",
      "tax_location_id" : 2,
      "kind" : "eu-b2c",
      "tax_entity_name" : "Belgium",
      "manual" : false,
      "tax_deducted" : false,
      "status" : "N",
      "evidence" : {
         "by_cc" : {
            "used" : true,
            "evidence_value" : "424242424",
            "resolved_country_code" : "BE",
            "evidence_type" : "by-cc"
         },
         "by_ip" : {
            "evidence_value" : "109.121.15.46",
            "used" : false,
            "evidence_type" : "by-ip",
            "resolved_country_code" : "RS"
         },
         "by_billing" : {
            "resolved_country_code" : "BE",
            "evidence_type" : "by-billing",
            "used" : true,
            "evidence_value" : "BE"
         }
      }
   },
   "storage_required_fields" : []
}

class CreateTransactionOut {
  transaction: class Transaction {
  invoiceDate: null
  invoiceAddress: null
  manual: false
  buyerCreditCardPrefix: 424242424
  customFields: []
  additionalCurrencies: null
  buyerTaxNumber: null
  customId: null
  deductedTaxAmount: 0
  taxCountryCode: BE
  forceCountryCode: null
  taxAmount: 17.36
  taxTimezone: GB
  buyerEmail: null
  originalTransactionKey: null
  test: true
  status: N
  createTimestamp: 2015-02-12T12:23:42Z
  totalAmount: 100.00
  taxEntityName: Belgium
  buyerIp: 77.105.25.33
  refundedTaxAmount: null
  countries: class Countries {
  by2003Rules: null
  detected: class CountrySchema {
  ccn3: 056
  name: Belgium
  code: BE
  codeLong: BEL
  cca2: BE
  callingCode: []
  cca3: BEL
  taxNumberCountryCode: BE
  codenum: 056
  taxSupported: true
}
  byTaxNumber: null
  byCc: class CountrySchema {
  ccn3: 056
  name: Belgium
  code: BE
  codeLong: BEL
  cca2: BE
  callingCode: []
  cca3: BEL
  taxNumberCountryCode: BE
  codenum: 056
  taxSupported: true
}
  byIp: class CountrySchema {
  ccn3: 688
  name: Serbia
  code: RS
  codeLong: SRB
  cca2: RS
  callingCode: []
  cca3: SRB
  taxNumberCountryCode: null
  codenum: 688
  taxSupported: false
}
  byToken: null
  byBilling: class CountrySchema {
  ccn3: 056
  name: Belgium
  code: BE
  codeLong: BEL
  cca2: BE
  callingCode: []
  cca3: BEL
  taxNumberCountryCode: BE
  codenum: 056
  taxSupported: true
}
  guessedFromIp: null
  forced: null
}
  invoicePlace: Killorglin232323
  verificationToken: null
  taxDeducted: false
  buyerName: null
  confirmTimestamp: null
  evidence: class Evidence {
  by2003Rules: null
  byPaymentMethod: null
  byTaxNumber: null
  byCc: class EvidenceSchema {
  used: true
  resolvedCountryCode: BE
  evidenceType: by-cc
  evidenceValue: 424242424
}
  byIp: class EvidenceSchema {
  used: false
  resolvedCountryCode: RS
  evidenceType: by-ip
  evidenceValue: 77.105.25.33
}
  byToken: null
  byBilling: class EvidenceSchema {
  used: true
  resolvedCountryCode: BE
  evidenceType: by-billing
  evidenceValue: BE
}
  guessedFromIp: null
  forced: null
}
  amount: 82.64
  customData: null
  billingCountryCode: BE
  taxSupported: true
  invoiceNumber: null
  currencyCode: EUR
  refundedTotalAmount: null
  description: null
  supplyDate: null
  transactionLines: [class TransactionLines {
  customFields: []
  additionalCurrencies: null
  customId: line1
  deductedTaxAmount: null
  productType: default
  quantity: 1
  taxAmount: 17.36
  unitPrice: 82.64
  unitOfMeasure: null
  totalAmount: 100.00
  taxRate: 21
  refundedTaxAmount: null
  lineKey: AGQwOqDZbbtQj1l9
  amount: 82.64
  id: null
  refundedTotalAmount: null
  informative: null
  description: null
  productCode: null
  supplyDate: null
  taxName: European VAT
}]
  orderDate: 2015-02-12T12:23:42Z
  key: TnwkAAAABaYOsHwNe-UNU3JtOYaU
}
  taxRequiredFields: []
  storageRequiredFields: []
}

Retrieve transaction
GET /api/v1/transactions/:key

Endpoint input

JSON schema
FieldTypeDescriptionRequired?
keystringTransaction keyYes
private_tokenstringPrivate token.No

Endpoint output

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction dataNo
    keystringId generated by taxamo.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    transaction_linesarrayTransaction lines.No
        idnumberGenerated id.No
        line_keystringGenerated line key.No
        custom_idstringCustom id, provided by ecommerce software.No
        product_typestringProduct type, according to dictionary /dictionaries/product_types. No
        total_amountnumberTotal amount. Required if amount or both unit price and quantity are not provided.No
        informativebooleanIf the line is provided for informative purposes. Such line must have :tax-rate and optionally :tax-name - if not, API validation will fail for this line.No
        amountnumberAmount. Required if total amount or both unit price and quantity are not provided.No
        quantitynumberQuantity Defaults to 1.No
        unit_pricenumberUnit price.No
        unit_of_measurestringUnit of measure.No
        supply_datestringDate of supply in yyyy-MM-dd format.No
        descriptionstringLine contents description.No
        product_codestringInternal product code, used for invoicing for example.No
        deducted_tax_amountnumberDeducted tax amount, calculated by taxmo.No
        deducted_tax_ratenumberDeducted tax rate, calculated by taxamo.No
        refunded_total_amountnumberRefunded total amount, calculated by taxmo.No
        refunded_tax_amountnumberRefunded tax amount, calculated by taxmo.No
        tax_ratenumberTax rate, calculated by taxamo. Must be provided when informative field is true.No
        tax_namestringTax name, calculated by taxamo. Can be overwritten when informative field is true.No
        tax_amountnumberTax amount, calculated by taxamo.No
        additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
            invoiceobjectInvoicing currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
            taxobjectTax-related currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
        custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
            keystringField's key.No
            valuestringField's value.No
        product_tax_codestringExternal product tax code for a line, for example TIC in US Sales tax.No
    testbooleanWas this transaction created in test mode?No
    manualbooleanIs the transaction created manually - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. If you need API to do that when accessing the API with private token, just skip the 'manual' flag or use false value there and provide customer's ip address through buyer_ip field. Manual mode is also used when using original_transaction_key field.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    confirm_timestampstringDate and time of transaction confirmation.No
    create_timestampstringDate and time of transaction creation.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_timezonestringTimezone name for tax transaction.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    tax_entity_namestringTo which entity is the tax due.No
    tax_entity_additional_idstringTax entity additional id.No
    total_amountnumberTotal amount of transaction.No
    amountnumberAmount of transaction without tax.No
    tax_amountnumberTax amount of transaction.No
    deducted_tax_amountnumberHow much tax has been deducted.No
    refunded_total_amountnumberTotal amount refunde (including tax).No
    refunded_tax_amountnumberRefunded tax amount.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    invoice_image_urlstringInvoice image URL - provided by Taxamo.No
    fully_informativebooleanSet to true if transaction has only informative lines.No
    kindstringTransaction kind: eu-b2c, eu-b2b, domestic, untaxedNo
    tax_supportedbooleanIs tax calculation supported for a detected tax location?No
    countriesobjectMap of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.No
        by_ipobjectCountry detected by IPNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        forcedobjectCountry forced by paramtersNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_billingobjectCountry detected by billing country codeNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_ccobjectCountry detected by credit card number prefixNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tokenobjectCountry detected from SMS tokenNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        detectedobjectCountry detected from other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        self_declarationobjectSelf declared country as evidence.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    buyer_tax_number_normalizedstringBuyer's tax number - normalized form.No
    buyer_tax_number_validbooleanIf the buyer tax number has been provided and was validated successfully. Always true for domestic transactions (billing country same as merchant's country), tax number doesn't get validated in that case.No
    buyer_tax_number_format_validbooleanIf the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.No
    tax_deductedbooleanIf the transaction is in a country supported by Taxamo, but the tax is not calculated due to merchant settings or EU B2B transaction for example.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    sourcestringTransaction source software - e.g. pluginNo
    external_keystringTransaction external keyNo
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    tax_number_servicestringTax number service identifier - if available for a given region and the region is enabled.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    warningsarrayWarnings for the transaction process, usually related to contacting B2B validation service.No
        typestringType of error.No
        messagestringError detailsNo
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
tax_required_fieldsarrayFields required for tax calculation. Depends on the region/transaction type.No
    field_namestringRequired field name.No
storage_required_fieldsarrayFields required for transaction storage (can be added later - it's up to merchant software). Depends on the region/transaction type.No
    field_namestringRequired field name.No

Authentication

Private token is required. It can be provided as:

  • Query string parameter, for example: GET /api/v1/transactions/:key?private_token=SamplePrivateTestKey1&...
  • As an HTTP header, such as: Private-Token: SampleTestPrivateKey1

Response codes

  • 200 - Success
  • 400 - Validation failed
  • 401 - Authentication error
  • 500 - Unexpected error

Example call

$ curl -H "Private-Token: SamplePrivateTestKey1" https://api.taxamo.com/api/v1/transactions/TYGYAAAABWvKsHyzI67tUz1As6Bc
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

GetTransactionOut result;

try {
    result = taxamoApi.getTransaction("TSwEAAAABZ9asHwNeDPVU3Jk70ig");
} catch (ApiException ae) {
    // handle exception
}

Example response

{
  "transaction": {
    "order_date": "2015-02-02T00:00:00Z",
    "status": "N",
    "buyer_name": "",
    "deducted_tax_amount": 0,
    "manual": true,
    "custom_fields": null,
    "transaction_lines": [
      {
        "line_key": "THdzq2QNFMmS1_7N",
        "custom_id": "1",
        "quantity": 1,
        "product_type": "default",
        "total_amount": 123.00,
        "amount": 100.00,
        "tax_amount": 23.00,
        "line_num": 1,
        "tax_name": "European VAT",
        "tax_rate": 23,
        "unit_price": 100.00
      }
    ],
    "create_timestamp": "2015-02-02T10:23:40Z",
    "key": "TYGYAAAABWvKsHyzI67tUz1As6Bc",
    "test": true,
    "tax_country_code": "IE",
    "tax_timezone": "GB",
    "invoice_address": {

    },
    "currency_code": "EUR",
    "total_amount": 123.00,
    "amount": 100.00,
    "tax_amount": 23.00,
    "evidence": null,
    "invoice_date": "2015-02-02T00:00:00Z",
    "additional_currencies": {
      "invoice": {

      }
    },
    "billing_country_code": "IE",
    "tax_entity_name": "Ireland",
    "update_timestamp": 1422872620077,
    "invoice_place": "Killorglin232323",
    "tax_supported": true,
    "supply_date": "2015-02-02T00:00:00Z"
  }
}
class GetTransactionOut {
  transaction: class Transaction {
  invoiceDate: 2015-02-10T00:00:00Z
  invoiceAddress: class InvoiceAddress {
  freeformAddress: null
  buildingNumber: 31
  streetName: Langford St
  addressDetail: null
  city: Killorglin
  postalCode: null
  region: Kerry
  country: null
}
  manual: true
  buyerCreditCardPrefix: 424242424
  customFields: []
  additionalCurrencies: class AdditionalCurrencies {
  invoice: class AdditionalCurrency {
  currencyCode: null
  amount: null
  taxAmount: null
  fxRate: null
  totalAmount: null
}}
  buyerTaxNumber: IE5251981413X
  customId: custom_id_121441
  deductedTaxAmount: 0
  taxCountryCode: IE
  forceCountryCode: null
  taxAmount: 0.00
  taxTimezone: GB
  buyerEmail: null
  originalTransactionKey: null
  test: true
  status: N
  createTimestamp: 2015-02-12T12:14:51Z
  totalAmount: 81.30
  taxEntityName: Ireland
  buyerIp: null
  refundedTaxAmount: null
  countries: null
  invoicePlace: Geneva, Switzerland
  verificationToken: null
  taxDeducted: true
  buyerName: null
  confirmTimestamp: null
  evidence: class Evidence {
  by2003Rules: null
  byPaymentMethod: null
  byTaxNumber: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: null
  evidenceValue: IE5251981413X
}
  byCc: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: null
  evidenceValue: 424242424
}
  byIp: null
  byToken: null
  byBilling: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: null
  evidenceValue: IE
}
  guessedFromIp: null
  forced: null
}
  amount: 81.30
  customData: null
  billingCountryCode: IE
  taxSupported: true
  invoiceNumber: 511414/2015
  currencyCode: EUR
  refundedTotalAmount: null
  description: null
  supplyDate: 2015-02-12T00:00:00Z
  transactionLines: [class TransactionLines {
  customFields: []
  additionalCurrencies: null
  customId: superKey
  deductedTaxAmount: null
  productType: e-service
  quantity: 1
  taxAmount: 0.00
  unitPrice: 81.30
  unitOfMeasure: null
  totalAmount: 81.30
  taxRate: 0
  refundedTaxAmount: null
  lineKey: 5Q9LWtNPGqVNunu-
  amount: 81.30
  id: null
  refundedTotalAmount: null
  informative: null
  description: hosting
  productCode: hosting_1
  supplyDate: null
  taxName: European VAT
}]
  orderDate: 2015-02-09T00:00:00Z
  key: TSwEAAAABZ9asHwNeDPVU3Jk70ig
}
  taxRequiredFields: []
  storageRequiredFields: []
}

Update transaction
PUT /api/v1/transactions/:key

Endpoint input

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction.No
    transaction_linesTransaction lines.No
    transaction_linesTransaction lines.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
private_tokenstringPrivate token.No
keystringTransaction key.No

Endpoint output

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction dataNo
    keystringId generated by taxamo.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    transaction_linesarrayTransaction lines.No
        idnumberGenerated id.No
        line_keystringGenerated line key.No
        custom_idstringCustom id, provided by ecommerce software.No
        product_typestringProduct type, according to dictionary /dictionaries/product_types. No
        total_amountnumberTotal amount. Required if amount or both unit price and quantity are not provided.No
        informativebooleanIf the line is provided for informative purposes. Such line must have :tax-rate and optionally :tax-name - if not, API validation will fail for this line.No
        amountnumberAmount. Required if total amount or both unit price and quantity are not provided.No
        quantitynumberQuantity Defaults to 1.No
        unit_pricenumberUnit price.No
        unit_of_measurestringUnit of measure.No
        supply_datestringDate of supply in yyyy-MM-dd format.No
        descriptionstringLine contents description.No
        product_codestringInternal product code, used for invoicing for example.No
        deducted_tax_amountnumberDeducted tax amount, calculated by taxmo.No
        deducted_tax_ratenumberDeducted tax rate, calculated by taxamo.No
        refunded_total_amountnumberRefunded total amount, calculated by taxmo.No
        refunded_tax_amountnumberRefunded tax amount, calculated by taxmo.No
        tax_ratenumberTax rate, calculated by taxamo. Must be provided when informative field is true.No
        tax_namestringTax name, calculated by taxamo. Can be overwritten when informative field is true.No
        tax_amountnumberTax amount, calculated by taxamo.No
        additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
            invoiceobjectInvoicing currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
            taxobjectTax-related currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
        custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
            keystringField's key.No
            valuestringField's value.No
        product_tax_codestringExternal product tax code for a line, for example TIC in US Sales tax.No
    testbooleanWas this transaction created in test mode?No
    manualbooleanIs the transaction created manually - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. If you need API to do that when accessing the API with private token, just skip the 'manual' flag or use false value there and provide customer's ip address through buyer_ip field. Manual mode is also used when using original_transaction_key field.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    confirm_timestampstringDate and time of transaction confirmation.No
    create_timestampstringDate and time of transaction creation.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_timezonestringTimezone name for tax transaction.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    tax_entity_namestringTo which entity is the tax due.No
    tax_entity_additional_idstringTax entity additional id.No
    total_amountnumberTotal amount of transaction.No
    amountnumberAmount of transaction without tax.No
    tax_amountnumberTax amount of transaction.No
    deducted_tax_amountnumberHow much tax has been deducted.No
    refunded_total_amountnumberTotal amount refunde (including tax).No
    refunded_tax_amountnumberRefunded tax amount.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    invoice_image_urlstringInvoice image URL - provided by Taxamo.No
    fully_informativebooleanSet to true if transaction has only informative lines.No
    kindstringTransaction kind: eu-b2c, eu-b2b, domestic, untaxedNo
    tax_supportedbooleanIs tax calculation supported for a detected tax location?No
    countriesobjectMap of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.No
        by_ipobjectCountry detected by IPNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        forcedobjectCountry forced by paramtersNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_billingobjectCountry detected by billing country codeNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_ccobjectCountry detected by credit card number prefixNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tokenobjectCountry detected from SMS tokenNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        detectedobjectCountry detected from other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        self_declarationobjectSelf declared country as evidence.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    buyer_tax_number_normalizedstringBuyer's tax number - normalized form.No
    buyer_tax_number_validbooleanIf the buyer tax number has been provided and was validated successfully. Always true for domestic transactions (billing country same as merchant's country), tax number doesn't get validated in that case.No
    buyer_tax_number_format_validbooleanIf the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.No
    tax_deductedbooleanIf the transaction is in a country supported by Taxamo, but the tax is not calculated due to merchant settings or EU B2B transaction for example.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    sourcestringTransaction source software - e.g. pluginNo
    external_keystringTransaction external keyNo
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    tax_number_servicestringTax number service identifier - if available for a given region and the region is enabled.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    warningsarrayWarnings for the transaction process, usually related to contacting B2B validation service.No
        typestringType of error.No
        messagestringError detailsNo
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
tax_required_fieldsarrayFields required for tax calculation. Depends on the region/transaction type.No
    field_namestringRequired field name.No
storage_required_fieldsarrayFields required for transaction storage (can be added later - it's up to merchant software). Depends on the region/transaction type.No
    field_namestringRequired field name.No

Authentication

Private token is required. It can be provided as:

  • Query string parameter, for example: PUT /api/v1/transactions/:key?private_token=SamplePrivateTestKey1&...
  • As an HTTP header, such as: Private-Token: SampleTestPrivateKey1
  • JSON input argument, for example: "private_token": "SamplePrivateTestKey1"

Response codes

  • 200 - Success
  • 400 - Validation failed
  • 401 - Authentication error
  • 500 - Unexpected error

Example call

$ curl -X PUT -H "Private-Token: SamplePrivateTestKey1" -H "Content-Type: application/json" -d \
'{
  "transaction": {
    "custom_id": "custom_id_121441",
    "order_date": "2013-11-14",
    "currency_code": "EUR",
    "billing_country_code": "IE",
    "buyer_credit_card_prefix": "424242424",
    "buyer_tax_number": "IE5251981413X",
    "tax_country_code": "IE",
    "tax_deducted": true,
    "tax_country_code": "IE",
    "buyer_ip": "127.0.0.1",
    "invoice_date": "2014-11-15",
    "invoice_place": "Geneva, Switzerland",
    "invoice_number": "511414/2013",
    "invoice_address": {
      "street_name": "Langford St",
      "building_number": "31",
      "city": "Killorglin",
      "region": "Kerry"
    },
    "transaction_lines": [
      {
        "custom_id": "line1",
        "line_key": "e_43E3wlNnpJ0tpj",
        "product_type": "e-service",
        "quantity": 1,
        "amount": 100,
        "description": "hosting",
        "product_code": "hosting_1"
      }
    ]
  }
}' \
https://api.taxamo.com/api/v1/transactions/TvNYAAAABSFKsHx6-KjhYDdhu0hQ
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

UpdateTransactionIn input = new UpdateTransactionIn();
Transaction transaction = new Transaction();
transaction.setCustomId("custom_id_121441");
transaction.setCurrencyCode("EUR");
transaction.setOrderDate("2015-02-09");
transaction.setBillingCountryCode("IE");
transaction.setBuyerCreditCardPrefix("424242424");
transaction.setBuyerTaxNumber("IE5251981413X");
transaction.setTaxCountryCode("IE");
transaction.setTaxDeducted(true);
transaction.setInvoiceDate("2015-02-10");
transaction.setInvoicePlace("Geneva, Switzerland");
transaction.setInvoiceNumber("511414/2015");
InvoiceAddress invoiceAddress = new InvoiceAddress();
invoiceAddress.setStreetName("Langford St");
invoiceAddress.setBuildingNumber("31");
invoiceAddress.setCity("Killorglin");
invoiceAddress.setRegion("Kerry");
transaction.setInvoiceAddress(invoiceAddress);
TransactionLines line = new TransactionLines();
line.setLineKey("3hnufRUoSd3T2TH5");
line.setCustomId("superKey");
line.setDescription("hosting");
line.setProductCode("hosting_1");
line.setProductType("e-service");
line.setTotalAmount(new BigDecimal("100"));
LinkedList lines = new LinkedList<TransactionLines>();
lines.push(line);
transaction.setTransactionLines(lines);
input.setTransaction(transaction);
UpdateTransactionOut result;

try {
    result = taxamoApi.updateTransaction("PhhEAAAABGNCsHwNemo5U3I4mCy0", input);
} catch (ApiException ae) {
    // handle exception
}

Example response

{
   "transaction" : {
      "status" : "N",
      "custom_id" : "custom_id_121441",
      "key" : "TvNYAAAABSFKsHx6-KjhYDdhu0hQ",
      "tax_number_service" : "vies",
      "total_amount" : 100,
      "additional_currencies" : {},
      "deducted_tax_amount" : 0,
      "currency_code" : "EUR",
      "invoice_date" : "2014-11-15T00:00:00Z",
      "evidence" : {
         "by_token" : {
            "used" : null,
            "evidence_type" : "by-token",
            "evidence_value" : null,
            "resolved_country_code" : null
         },
         "by_ip" : {
            "used" : null,
            "evidence_value" : "127.0.0.1",
            "resolved_country_code" : null,
            "evidence_type" : "by-ip"
         },
         "by_cc" : {
            "resolved_country_code" : null,
            "evidence_value" : "424242424",
            "evidence_type" : "by-cc",
            "used" : null
         },
         "forced" : {
            "evidence_type" : "forced",
            "resolved_country_code" : null,
            "evidence_value" : null,
            "used" : null
         },
         "by_tax_number" : {
            "evidence_type" : "by-tax-number",
            "evidence_value" : "IE5251981413X",
            "resolved_country_code" : null,
            "used" : null
         },
         "by_billing" : {
            "evidence_type" : "by-billing",
            "resolved_country_code" : null,
            "evidence_value" : "IE",
            "used" : null
         }
      },
      "transaction_lines" : [
         {
            "unit_price" : 100,
            "amount" : 100,
            "tax_amount" : 0,
            "tax_rate" : 0,
            "tax_name" : "European VAT",
            "description" : "hosting",
            "product_code" : "hosting_1",
            "total_amount" : 100,
            "line_key" : "e_43E3wlNnpJ0tpj",
            "product_type" : "e-service",
            "custom_id" : "line1",
            "quantity" : 1
         }
      ],
      "create_timestamp" : "2016-10-24T09:46:22Z",
      "tax_timezone" : "GB",
      "buyer_credit_card_prefix" : "424242424",
      "order_date" : "2013-11-14T00:00:00Z",
      "buyer_tax_number" : "IE5251981413X",
      "tax_amount" : 0,
      "tax_entity_name" : "Ireland",
      "amount" : 100,
      "refunded_tax_amount" : 0,
      "custom_fields" : null,
      "invoice_place" : "Geneva, Switzerland",
      "tax_deducted" : true,
      "tax_supported" : true,
      "buyer_ip" : "127.0.0.1",
      "tax_country_code" : "IE",
      "kind" : "eu-b2b",
      "invoice_number" : "511414/2013",
      "invoice_address" : {
         "building_number" : "31",
         "street_name" : "Langford St",
         "region" : "Kerry",
         "city" : "Killorglin"
      },
      "fully_informative" : false,
      "update_timestamp" : 1477302382785,
      "billing_country_code" : "IE",
      "test" : true,
      "tax_region" : "EU",
      "tax_required_fields" : [],
      "refunded_total_amount" : 0,
      "storage_required_fields" : []
   }
}

class UpdateTransactionOut {
  transaction: class Transaction {
  invoiceDate: 2015-02-10T00:00:00Z
  invoiceAddress: class InvoiceAddress {
  freeformAddress: null
  buildingNumber: 31
  streetName: Langford St
  addressDetail: null
  city: Killorglin
  postalCode: null
  region: Kerry
  country: null
}
  manual: true
  buyerCreditCardPrefix: 424242424
  customFields: []
  additionalCurrencies: class AdditionalCurrencies {
  invoice: class AdditionalCurrency {
  currencyCode: null
  amount: null
  taxAmount: null
  fxRate: null
  totalAmount: null
}}
  buyerTaxNumber: IE5251981413X
  customId: custom_id_121441
  deductedTaxAmount: 0
  taxCountryCode: IE
  forceCountryCode: null
  taxAmount: 0.00
  taxTimezone: GB
  buyerEmail: null
  originalTransactionKey: null
  test: true
  status: N
  createTimestamp: 2015-02-12T12:14:51Z
  totalAmount: 81.30
  taxEntityName: Austria
  buyerIp: null
  refundedTaxAmount: null
  countries: null
  invoicePlace: Geneva, Switzerland
  verificationToken: null
  taxDeducted: true
  buyerName: null
  confirmTimestamp: null
  evidence: class Evidence {
  by2003Rules: null
  byPaymentMethod: null
  byTaxNumber: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-tax-number
  evidenceValue: IE5251981413X
}
  byCc: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-cc
  evidenceValue: 424242424
}
  byIp: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-ip
  evidenceValue: null
}
  byToken: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-token
  evidenceValue: null
}
  byBilling: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-billing
  evidenceValue: IE
}
  guessedFromIp: null
  forced: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: forced
  evidenceValue: null
}}
  amount: 81.30
  customData: null
  billingCountryCode: IE
  taxSupported: true
  invoiceNumber: 511414/2015
  currencyCode: EUR
  refundedTotalAmount: null
  description: null
  supplyDate: 2015-02-12T00:00:00Z
  transactionLines: [class TransactionLines {
  customFields: []
  additionalCurrencies: null
  customId: superKey
  deductedTaxAmount: null
  productType: e-service
  quantity: 1
  taxAmount: 0.00
  unitPrice: 81.30
  unitOfMeasure: null
  totalAmount: 81.30
  taxRate: 0
  refundedTaxAmount: null
  lineKey: 3hnufRUoSd3T2TH5
  amount: 81.30
  id: null
  refundedTotalAmount: null
  informative: null
  description: hosting
  productCode: hosting_1
  supplyDate: null
  taxName: European VAT
}]
  orderDate: 2015-02-09T00:00:00Z
  key: TSwEAAAABZ9asHwNeDPVU3Jk70ig
}
  taxRequiredFields: []
  storageRequiredFields: []
}

Confirm transaction
POST /api/v1/transactions/:key/confirm

Endpoint input

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction.No
    transaction_linesTransaction lines.No
    transaction_linesTransaction lines.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
private_tokenstringPrivate token.No
keystringTransaction key.No

Endpoint output

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction dataNo
    keystringId generated by taxamo.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    transaction_linesarrayTransaction lines.No
        idnumberGenerated id.No
        line_keystringGenerated line key.No
        custom_idstringCustom id, provided by ecommerce software.No
        product_typestringProduct type, according to dictionary /dictionaries/product_types. No
        total_amountnumberTotal amount. Required if amount or both unit price and quantity are not provided.No
        informativebooleanIf the line is provided for informative purposes. Such line must have :tax-rate and optionally :tax-name - if not, API validation will fail for this line.No
        amountnumberAmount. Required if total amount or both unit price and quantity are not provided.No
        quantitynumberQuantity Defaults to 1.No
        unit_pricenumberUnit price.No
        unit_of_measurestringUnit of measure.No
        supply_datestringDate of supply in yyyy-MM-dd format.No
        descriptionstringLine contents description.No
        product_codestringInternal product code, used for invoicing for example.No
        deducted_tax_amountnumberDeducted tax amount, calculated by taxmo.No
        deducted_tax_ratenumberDeducted tax rate, calculated by taxamo.No
        refunded_total_amountnumberRefunded total amount, calculated by taxmo.No
        refunded_tax_amountnumberRefunded tax amount, calculated by taxmo.No
        tax_ratenumberTax rate, calculated by taxamo. Must be provided when informative field is true.No
        tax_namestringTax name, calculated by taxamo. Can be overwritten when informative field is true.No
        tax_amountnumberTax amount, calculated by taxamo.No
        additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
            invoiceobjectInvoicing currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
            taxobjectTax-related currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
        custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
            keystringField's key.No
            valuestringField's value.No
        product_tax_codestringExternal product tax code for a line, for example TIC in US Sales tax.No
    testbooleanWas this transaction created in test mode?No
    manualbooleanIs the transaction created manually - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. If you need API to do that when accessing the API with private token, just skip the 'manual' flag or use false value there and provide customer's ip address through buyer_ip field. Manual mode is also used when using original_transaction_key field.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    confirm_timestampstringDate and time of transaction confirmation.No
    create_timestampstringDate and time of transaction creation.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_timezonestringTimezone name for tax transaction.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    tax_entity_namestringTo which entity is the tax due.No
    tax_entity_additional_idstringTax entity additional id.No
    total_amountnumberTotal amount of transaction.No
    amountnumberAmount of transaction without tax.No
    tax_amountnumberTax amount of transaction.No
    deducted_tax_amountnumberHow much tax has been deducted.No
    refunded_total_amountnumberTotal amount refunde (including tax).No
    refunded_tax_amountnumberRefunded tax amount.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    invoice_image_urlstringInvoice image URL - provided by Taxamo.No
    fully_informativebooleanSet to true if transaction has only informative lines.No
    kindstringTransaction kind: eu-b2c, eu-b2b, domestic, untaxedNo
    tax_supportedbooleanIs tax calculation supported for a detected tax location?No
    countriesobjectMap of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.No
        by_ipobjectCountry detected by IPNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        forcedobjectCountry forced by paramtersNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_billingobjectCountry detected by billing country codeNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_ccobjectCountry detected by credit card number prefixNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tokenobjectCountry detected from SMS tokenNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        detectedobjectCountry detected from other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        self_declarationobjectSelf declared country as evidence.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    buyer_tax_number_normalizedstringBuyer's tax number - normalized form.No
    buyer_tax_number_validbooleanIf the buyer tax number has been provided and was validated successfully. Always true for domestic transactions (billing country same as merchant's country), tax number doesn't get validated in that case.No
    buyer_tax_number_format_validbooleanIf the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.No
    tax_deductedbooleanIf the transaction is in a country supported by Taxamo, but the tax is not calculated due to merchant settings or EU B2B transaction for example.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    sourcestringTransaction source software - e.g. pluginNo
    external_keystringTransaction external keyNo
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    tax_number_servicestringTax number service identifier - if available for a given region and the region is enabled.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    warningsarrayWarnings for the transaction process, usually related to contacting B2B validation service.No
        typestringType of error.No
        messagestringError detailsNo
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
tax_required_fieldsarrayFields required for tax calculation. Depends on the region/transaction type.No
    field_namestringRequired field name.No
storage_required_fieldsarrayFields required for transaction storage (can be added later - it's up to merchant software). Depends on the region/transaction type.No
    field_namestringRequired field name.No

Authentication

Private token is required. It can be provided as:

  • Query string parameter, for example: POST /api/v1/transactions/:key/confirm?private_token=SamplePrivateTestKey1&...
  • As an HTTP header, such as: Private-Token: SampleTestPrivateKey1
  • JSON input argument, for example: "private_token": "SamplePrivateTestKey1"

Response codes

  • 200 - Success
  • 400 - Validation failed
  • 401 - Authentication error
  • 500 - Unexpected error

Example call

$ curl -X 'POST' 'https://api.taxamo.com/api/v1/transactions/TvNYAAAABSFKsHx6-KjhYDdhu0hQ/confirm?private_token=SamplePrivateTestKey1'
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

ConfirmTransactionIn input = new ConfirmTransactionIn();
ConfirmTransactionOut result;

try {
    result = taxamoApi.confirmTransaction("TSwEAAAABZ9asHwNeDPVU3Jk70ig", input);
} catch (ApiException ae) {
    // handle exception
}

Example response

{
   "transaction" : {
      "custom_fields" : null,
      "tax_entity_name" : "Ireland",
      "tax_deducted" : true,
      "tax_required_fields" : [],
      "additional_currencies" : {},
      "tax_supported" : true,
      "refunded_total_amount" : 0,
      "update_timestamp" : 1477302544578,
      "invoice_date" : "2014-11-15T00:00:00Z",
      "tax_timezone" : "GB",
      "custom_id" : "custom_id_121441",
      "buyer_tax_number" : "IE5251981413X",
      "amount" : 100,
      "invoice_address" : {
         "street_name" : "Langford St",
         "building_number" : "31",
         "city" : "Killorglin",
         "region" : "Kerry"
      },
      "status" : "C",
      "buyer_ip" : "127.0.0.1",
      "invoice_number" : "511414/2013",
      "create_timestamp" : "2016-10-24T09:46:22Z",
      "transaction_lines" : [
         {
            "product_type" : "e-service",
            "total_amount" : 100,
            "quantity" : 1,
            "unit_price" : 100,
            "tax_rate" : 0,
            "tax_amount" : 0,
            "amount" : 100,
            "line_key" : "1atQhzXRqCJ3ELhM",
            "custom_id" : "line1",
            "description" : "hosting",
            "product_code" : "hosting_1",
            "tax_name" : "European VAT",
            "deducted_tax_amount" : 0,
            "line_num" : 1
         }
      ],
      "currency_code" : "EUR",
      "total_amount" : 100,
      "tax_region" : "EU",
      "test" : true,
      "deducted_tax_amount" : 0,
      "invoice_place" : "Geneva, Switzerland",
      "tax_number_service" : "vies",
      "storage_required_fields" : [],
      "refunded_tax_amount" : 0,
      "tax_amount" : 0,
      "buyer_credit_card_prefix" : "424242424",
      "evidence" : {
         "by_billing" : {
            "evidence_type" : "by-billing",
            "used" : null,
            "resolved_country_code" : null,
            "evidence_value" : "IE"
         },
         "by_ip" : {
            "evidence_value" : "127.0.0.1",
            "resolved_country_code" : null,
            "used" : null,
            "evidence_type" : "by-ip"
         },
         "forced" : {
            "evidence_value" : null,
            "evidence_type" : "forced",
            "resolved_country_code" : null,
            "used" : null
         },
         "by_tax_number" : {
            "resolved_country_code" : null,
            "used" : null,
            "evidence_type" : "by-tax-number",
            "evidence_value" : "IE5251981413X"
         },
         "by_cc" : {
            "evidence_type" : "by-cc",
            "used" : null,
            "resolved_country_code" : null,
            "evidence_value" : "424242424"
         },
         "by_token" : {
            "evidence_value" : null,
            "resolved_country_code" : null,
            "used" : null,
            "evidence_type" : "by-token"
         }
      },
      "kind" : "eu-b2b",
      "fully_informative" : false,
      "order_date" : "2013-11-14T00:00:00Z",
      "tax_country_code" : "IE",
      "confirm_timestamp" : "2016-10-24T09:51:36Z",
      "key" : "TvNYAAAABSFKsHx6-KjhYDdhu0hQ",
      "billing_country_code" : "IE"
   }
}
class ConfirmTransactionOut {
  transaction: class Transaction {
  invoiceDate: 2015-02-10T00:00:00Z
  invoiceAddress: class InvoiceAddress {
  freeformAddress: null
  buildingNumber: 31
  streetName: Langford St
  addressDetail: null
  city: Killorglin
  postalCode: null
  region: Kerry
  country: null
}
  manual: true
  buyerCreditCardPrefix: 424242424
  customFields: []
  additionalCurrencies: class AdditionalCurrencies {
  invoice: class AdditionalCurrency {
  currencyCode: null
  amount: null
  taxAmount: null
  fxRate: null
  totalAmount: null
}}
  buyerTaxNumber: IE5251981413X
  customId: custom_id_121441
  deductedTaxAmount: 0.00
  taxCountryCode: IE
  forceCountryCode: null
  taxAmount: 0.00
  taxTimezone: GB
  buyerEmail: null
  null //?originalTransactionKey: null
  test: true
  status: C
  createTimestamp: 2015-02-12T12:14:51Z
  totalAmount: 81.30
  taxEntityName: Ireland
  buyerIp: null
  refundedTaxAmount: null
  countries: null
  invoicePlace: Geneva, Switzerland
  verificationToken: null
  taxDeducted: true
  buyerName: null
  confirmTimestamp: 2015-02-12T12:26:40Z
  evidence: class Evidence {
  by2003Rules: null
  byPaymentMethod: null
  byTaxNumber: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-tax-number
  evidenceValue: IE5251981413X
}
  byCc: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-cc
  evidenceValue: 424242424
}
  byIp: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-ip
  evidenceValue: null
}
  byToken: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-token
  evidenceValue: null
}
  byBilling: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: by-billing
  evidenceValue: IE
}
  guessedFromIp: null
  forced: class EvidenceSchema {
  used: null
  resolvedCountryCode: null
  evidenceType: forced
  evidenceValue: null
}}
  amount: 81.30
  customData: null
  billingCountryCode: IE
  taxSupported: true
  invoiceNumber: 511414/2015
  currencyCode: EUR
  refundedTotalAmount: null
  description: null
  supplyDate: 2015-02-12T00:00:00Z
  transactionLines: [class TransactionLines {
  customFields: []
  additionalCurrencies: null
  customId: superKey
  deductedTaxAmount: 0.00
  productType: e-service
  quantity: 1
  taxAmount: 0.00
  unitPrice: 81.30
  unitOfMeasure: null
  totalAmount: 81.30
  taxRate: 0
  refundedTaxAmount: null
  lineKey: 5Q9LWtNPGqVNunu-
  amount: 81.30
  id: null
  refundedTotalAmount: null
  informative: null
  description: hosting
  productCode: hosting_1
  supplyDate: null
  taxName: European VAT
}]
  orderDate: 2015-02-09T00:00:00Z
  key: TSwEAAAABZ9asHwNeDPVU3Jk70ig
}
  taxRequiredFields: []
  storageRequiredFields: []
}

Delete transaction
DELETE /api/v1/transactions/:key

Endpoint input

JSON schema
FieldTypeDescriptionRequired?
keystringTransaction keyNo
private_tokenstringPrivate token.No

Endpoint output

JSON schema
FieldTypeDescriptionRequired?
successbooleanWas operation successful?No

Authentication

Private token is required. It can be provided as:

  • Query string parameter, for example: DELETE /api/v1/transactions/:key?private_token=SamplePrivateTestKey1&...
  • As an HTTP header, such as: Private-Token: SampleTestPrivateKey1
  • JSON input argument, for example: "private_token": "SamplePrivateTestKey1"

Response codes

  • 200 - Success
  • 400 - Validation failed
  • 401 - Authentication error
  • 500 - Unexpected error

Example call

$ curl -X DELETE -H "Private-Token: SamplePrivateTestKey1" https://api.taxamo.com/api/v1/transactions/tr_test_zzcFWpLYeJ6g5oDetG7bGHpeOsA
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

CancelTransactionOut result;

try {
    result = taxamoApi.cancelTransaction("TnwkAAAABaYOsHwNe-UNU3JtOYaU");
} catch (ApiException ae) {
    // handle exception
}

Example response

{"success": true}
class CancelTransactionOut {
  success: true
}

Un-confirm the transaction
POST /api/v1/transactions/:key/unconfirm

Un-confirmed transaction can be edited or canceled like a newly created one.

Endpoint input

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction.No
    transaction_linesTransaction lines.No
    transaction_linesTransaction lines.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
private_tokenstringPrivate token.No
keystringTransaction key.No

Endpoint output

JSON schema
FieldTypeDescriptionRequired?
transactionobjectTransaction dataNo
    keystringId generated by taxamo.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    transaction_linesarrayTransaction lines.No
        idnumberGenerated id.No
        line_keystringGenerated line key.No
        custom_idstringCustom id, provided by ecommerce software.No
        product_typestringProduct type, according to dictionary /dictionaries/product_types. No
        total_amountnumberTotal amount. Required if amount or both unit price and quantity are not provided.No
        informativebooleanIf the line is provided for informative purposes. Such line must have :tax-rate and optionally :tax-name - if not, API validation will fail for this line.No
        amountnumberAmount. Required if total amount or both unit price and quantity are not provided.No
        quantitynumberQuantity Defaults to 1.No
        unit_pricenumberUnit price.No
        unit_of_measurestringUnit of measure.No
        supply_datestringDate of supply in yyyy-MM-dd format.No
        descriptionstringLine contents description.No
        product_codestringInternal product code, used for invoicing for example.No
        deducted_tax_amountnumberDeducted tax amount, calculated by taxmo.No
        deducted_tax_ratenumberDeducted tax rate, calculated by taxamo.No
        refunded_total_amountnumberRefunded total amount, calculated by taxmo.No
        refunded_tax_amountnumberRefunded tax amount, calculated by taxmo.No
        tax_ratenumberTax rate, calculated by taxamo. Must be provided when informative field is true.No
        tax_namestringTax name, calculated by taxamo. Can be overwritten when informative field is true.No
        tax_amountnumberTax amount, calculated by taxamo.No
        additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
            invoiceobjectInvoicing currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
            taxobjectTax-related currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
        custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
            keystringField's key.No
            valuestringField's value.No
        product_tax_codestringExternal product tax code for a line, for example TIC in US Sales tax.No
    testbooleanWas this transaction created in test mode?No
    manualbooleanIs the transaction created manually - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. If you need API to do that when accessing the API with private token, just skip the 'manual' flag or use false value there and provide customer's ip address through buyer_ip field. Manual mode is also used when using original_transaction_key field.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    confirm_timestampstringDate and time of transaction confirmation.No
    create_timestampstringDate and time of transaction creation.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_timezonestringTimezone name for tax transaction.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    tax_entity_namestringTo which entity is the tax due.No
    tax_entity_additional_idstringTax entity additional id.No
    total_amountnumberTotal amount of transaction.No
    amountnumberAmount of transaction without tax.No
    tax_amountnumberTax amount of transaction.No
    deducted_tax_amountnumberHow much tax has been deducted.No
    refunded_total_amountnumberTotal amount refunde (including tax).No
    refunded_tax_amountnumberRefunded tax amount.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    invoice_image_urlstringInvoice image URL - provided by Taxamo.No
    fully_informativebooleanSet to true if transaction has only informative lines.No
    kindstringTransaction kind: eu-b2c, eu-b2b, domestic, untaxedNo
    tax_supportedbooleanIs tax calculation supported for a detected tax location?No
    countriesobjectMap of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.No
        by_ipobjectCountry detected by IPNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        forcedobjectCountry forced by paramtersNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_billingobjectCountry detected by billing country codeNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_ccobjectCountry detected by credit card number prefixNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tokenobjectCountry detected from SMS tokenNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        detectedobjectCountry detected from other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        self_declarationobjectSelf declared country as evidence.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    buyer_tax_number_normalizedstringBuyer's tax number - normalized form.No
    buyer_tax_number_validbooleanIf the buyer tax number has been provided and was validated successfully. Always true for domestic transactions (billing country same as merchant's country), tax number doesn't get validated in that case.No
    buyer_tax_number_format_validbooleanIf the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.No
    tax_deductedbooleanIf the transaction is in a country supported by Taxamo, but the tax is not calculated due to merchant settings or EU B2B transaction for example.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    sourcestringTransaction source software - e.g. pluginNo
    external_keystringTransaction external keyNo
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    tax_number_servicestringTax number service identifier - if available for a given region and the region is enabled.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    warningsarrayWarnings for the transaction process, usually related to contacting B2B validation service.No
        typestringType of error.No
        messagestringError detailsNo
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No
tax_required_fieldsarrayFields required for tax calculation. Depends on the region/transaction type.No
    field_namestringRequired field name.No
storage_required_fieldsarrayFields required for transaction storage (can be added later - it's up to merchant software). Depends on the region/transaction type.No
    field_namestringRequired field name.No

Authentication

Private token is required. It can be provided as:

  • Query string parameter, for example: POST /api/v1/transactions/:key/unconfirm?private_token=SamplePrivateTestKey1&...
  • As an HTTP header, such as: Private-Token: SampleTestPrivateKey1
  • JSON input argument, for example: "private_token": "SamplePrivateTestKey1"

Response codes

  • 200 - Success
  • 400 - Validation failed
  • 401 - Authentication error
  • 500 - Unexpected error

Example call

$ curl -X 'POST' 'https://api.taxamo.com/api/v1/transactions/TvNYAAAABSFKsHx6-KjhYDdhu0hQ/unconfirm?private_token=SamplePrivateTestKey1'
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

UnconfirmTransactionIn input = new UnconfirmTransactionIn();
UnconfirmTransactionOut result = null;

try {
   result = taxamoApi.unconfirmTransaction("TtsEAABJsHkCsHxZepYZYFyWKw7w", input);
} catch (ApiException ae) {
   // handle exception
}
System.out.println("result: " + result);

Example response

{
   "transaction" : {
      "tax_deducted" : true,
      "transaction_lines" : [
         {
            "line_num" : 1,
            "num" : null,
            "product_type" : "e-service",
            "product_code" : "hosting_1",
            "unit_price" : 100,
            "deducted_tax_amount" : 0,
            "description" : "hosting",
            "tax_name" : "European VAT",
            "custom_id" : "line1",
            "total_amount" : 100,
            "tax_rate" : 0,
            "quantity" : 1,
            "tax_amount" : 0,
            "amount" : 100,
            "line_key" : "1atQhzXRqCJ3ELhM"
         }
      ],
      "status" : "N",
      "evidence" : {
         "by_ip" : {
            "resolved_country_code" : "RS",
            "evidence_value" : "127.0.0.1",
            "used" : false,
            "evidence_type" : "by-ip"
         },
         "by_tax_number" : {
            "evidence_value" : "IE5251981413X"
         },
         "by_billing" : {
            "evidence_type" : "by-billing",
            "evidence_value" : "BE",
            "resolved_country_code" : "BE",
            "used" : true
         },
         "by_cc" : {
            "used" : true,
            "resolved_country_code" : "BE",
            "evidence_value" : "424242424",
            "evidence_type" : "by-cc"
         }
      },
      "tax_region" : "EU",
      "tax_timezone" : "GB",
      "tax_country_code" : "IE",
      "tax_number_service" : "vies",
      "confirm_timestamp" : "2016-10-24T09:51:36Z",
      "buyer_tax_number" : "IE5251981413X",
      "create_timestamp" : "2016-10-24T09:46:22Z",
      "tax_supported" : true,
      "custom_fields" : null,
      "order_date" : "2013-11-14T00:00:00Z",
      "currency_code" : "EUR",
      "billing_country_code" : "IE",
      "invoice_place" : "Geneva, Switzerland",
      "key" : "TvNYAAAABSFKsHx6-KjhYDdhu0hQ",
      "additional_currencies" : {},
      "tax_entity_name" : "Ireland",
      "kind" : "eu-b2b",
      "fully_informative" : false,
      "update_timestamp" : 1477302739920,
      "refunded_tax_amount" : 0,
      "buyer_credit_card_prefix" : "424242424",
      "invoice_number" : "511414/2013",
      "buyer_ip" : "127.0.0.1",
      "tax_amount" : 0,
      "amount" : 100,
      "refunded_total_amount" : 0,
      "test" : true,
      "deducted_tax_amount" : 0,
      "total_amount" : 100,
      "custom_id" : "custom_id_121441",
      "invoice_address" : {
         "building_number" : "31",
         "street_name" : "Langford St",
         "city" : "Killorglin",
         "region" : "Kerry"
      },
      "invoice_date" : "2014-11-15T00:00:00Z"
   }
}
class UnconfirmTransactionOut {
  transaction: class Transaction {
  confirmTimestamp: 2016-10-31T11:05:46Z
  fullyInformative: false
  deductedTaxAmount: 0
  buyerCreditCardPrefix: null
  customData: null
  buyerName: First Lipski
  invoiceDate: null
  createTimestamp: 2016-10-31T11:05:46Z
  currencyCode: USD
  supplyDate: null
  invoiceImageUrl: https://invoicestaxamo.s3.amazonaws.com/TtsEAABJsHkCsHxZepYZYFyWKw7w/invoice.html
  key: TtsEAABJsHkCsHxZepYZYFyWKw7w
  invoiceAddress: class InvoiceAddress {
  freeformAddress: 1 Main St San Jose CA 95131
  buildingNumber: null
  streetName: 1 Main St
  addressDetail: null
  city: San Jose
  postalCode: 95131
  region: CA
  country: null
}
  buyerTaxNumberValid: null
  verificationToken: null
  taxSupported: true
  taxData: null
  transactionLines: [class TransactionLines {
  productType: null
  deductedTaxAmount: null
  supplyDate: null
  id: null
  unitPrice: 0.81
  unitOfMeasure: null
  quantity: 1
  customFields: []
  lineKey: OqwHMY50_eS3Y8No
  taxName: European VAT
  productCode: null
  amount: 0.81
  customId: 1
  informative: null
  taxAmount: 0.19
  taxRate: 23
  additionalCurrencies: null
  totalAmount: 1.0
  productTaxCode: null
  refundedTaxAmount: null
  description: Example Item
  refundedTotalAmount: null
}]
  buyerTaxNumber: null
  externalKey: null
  status: N
  customFields: [class CustomFields {
  key: paypal-profileid
  value: I-GKDXDSLTUMBE
}
, class CustomFields {
  key: paypal-payerid
  value: E3PAVVVMR5B68
}
, class CustomFields {
  key: paypal-token
  value: EC-90B63553AG847374K
}]
  forceCountryCode: null
  countries: null
  invoiceNumber: PL2016-88
  orderDate: 2016-11-01T01:05:35Z
  customerId: null
  kind: eu-b2c
  source: PayPal webhook in Taxamo
  amount: 0.81
  buyerIp: 79.175.86.228
  buyerEmail: paypal-demo-buyer3@taxamo.com
  originalTransactionKey: TJnwAABJszIKsHxrhyH1W1B0_zos
  billingCountryCode: PL
  customId: 8AT36827JF336830J
  taxAmount: 0.19
  additionalCurrencies: class AdditionalCurrencies {
  invoice: null
}
  invoicePlace: Beograd, Garsije Lorke 37/6
  totalAmount: 1.0
  taxEntityName: Poland
  evidence: class Evidence {
  byToken: null
  byCc: null
  by2003Rules: null
  forced: null
  byPaymentMethod: class EvidenceSchema {
  used: false
  resolvedCountryCode: US
  evidenceType: by-payment-method
  evidenceValue: US
}
  byIp: class EvidenceSchema {
  used: false
  resolvedCountryCode: RS
  evidenceType: by-ip
  evidenceValue: 79.175.86.228
}
  guessedFromIp: null
  otherCommerciallyRelevantInfo: null
  byBilling: class EvidenceSchema {
  used: true
  resolvedCountryCode: PL
  evidenceType: by-billing
  evidenceValue: PL
}
  byTaxNumber: null
  selfDeclaration: class EvidenceSchema {
  used: true
  resolvedCountryCode: PL
  evidenceType: self-declaration
  evidenceValue: PL
}}
  refundedTaxAmount: 0
  manual: true
  taxTimezone: Pacific/Kiritimati
  description: Example Item
  test: true
  taxDeducted: null
  taxCountryCode: PL
  refundedTotalAmount: 0
}
  taxRequiredFields: []
  storageRequiredFields: []
}

Browse transactions
GET /api/v1/transactions/

Endpoint input

JSON schema
FieldTypeDescriptionRequired?
private_tokenstringPrivate token.No
order_date_fromstringOrder date from in yyyy-MM-dd format.No
order_date_tostringOrder date to in yyyy-MM-dd format.No
sort_reversebooleanIf true, results are sorted in descending order.No
filter_textstringFiltering expression. Placeholder field, not supported yet.No
limitintegerLimit (no more than 1000, defaults to 100).No
offsetintegerOffsetNo
formatstringOutput format - supports 'csv' value for this operation.No
tax_country_codestringTwo letter ISO tax country code.No
tax_country_codesstringComma separated list of two letter ISO tax country codes.No
currency_codestringThree letter ISO currency code.No
statusesstringComma separated list of of transaction statuses. 'N' - unconfirmed transaction, 'C' - confirmed transaction.No
key_or_custom_idstringTaxamo provided transaction key or custom idNo
original_transaction_keystringTaxamo provided original transaction keyNo
invoice_numberstringTransaction invoice number.No
total_amount_greater_thanstringReturn only transactions with total amount greater than given number. Transactions with total amount equal to a given number (e.g. 0) are not returned.No
total_amount_less_thanstringReturn only transactions with total amount less than a given number. Transactions with total amount equal to a given number (e.g. 1) are not returned.No
has_notebooleanReturn only transactions with a note field set.No

Endpoint output

JSON schema
FieldTypeDescriptionRequired?
transactionsarrayTransactions matching the criteria.No
    keystringId generated by taxamo.No
    currency_codestringCurrency code for transaction - e.g. EUR.No
    transaction_linesarrayTransaction lines.No
        idnumberGenerated id.No
        line_keystringGenerated line key.No
        custom_idstringCustom id, provided by ecommerce software.No
        product_typestringProduct type, according to dictionary /dictionaries/product_types. No
        total_amountnumberTotal amount. Required if amount or both unit price and quantity are not provided.No
        informativebooleanIf the line is provided for informative purposes. Such line must have :tax-rate and optionally :tax-name - if not, API validation will fail for this line.No
        amountnumberAmount. Required if total amount or both unit price and quantity are not provided.No
        quantitynumberQuantity Defaults to 1.No
        unit_pricenumberUnit price.No
        unit_of_measurestringUnit of measure.No
        supply_datestringDate of supply in yyyy-MM-dd format.No
        descriptionstringLine contents description.No
        product_codestringInternal product code, used for invoicing for example.No
        deducted_tax_amountnumberDeducted tax amount, calculated by taxmo.No
        deducted_tax_ratenumberDeducted tax rate, calculated by taxamo.No
        refunded_total_amountnumberRefunded total amount, calculated by taxmo.No
        refunded_tax_amountnumberRefunded tax amount, calculated by taxmo.No
        tax_ratenumberTax rate, calculated by taxamo. Must be provided when informative field is true.No
        tax_namestringTax name, calculated by taxamo. Can be overwritten when informative field is true.No
        tax_amountnumberTax amount, calculated by taxamo.No
        additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
            invoiceobjectInvoicing currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
            taxobjectTax-related currency information.No
                currency_codestring3-letter ISO currency code.No
                amountnumberAmount (w/o TAX) in designated currency.No
                tax_amountnumberTax amount in designated currency.No
                fx_ratenumberForeign exchange rate used in calculationNo
                fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
                total_amountnumberTotal amount in designated currency.No
        custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
            keystringField's key.No
            valuestringField's value.No
        product_tax_codestringExternal product tax code for a line, for example TIC in US Sales tax.No
    testbooleanWas this transaction created in test mode?No
    manualbooleanIs the transaction created manually - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. If you need API to do that when accessing the API with private token, just skip the 'manual' flag or use false value there and provide customer's ip address through buyer_ip field. Manual mode is also used when using original_transaction_key field.No
    custom_idstringCustom identifier provided upon transaction creation.No
    customer_idstringFree-form field for storing customer id.No
    custom_datastringCustom data related to transaction.No
    descriptionstringTransaction description.No
    statusstringTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in store-transaction! with private-token to create confirmed transaction, otherwise 'N' is default status. Not applicable for update-transaction!.No
    order_datestringOrder date in yyyy-MM-dd or yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format, in merchant's timezone. If provided by the API caller, no timezone conversion is performed. Default value is current date and time in merchant's timezone. When using public token, the default value is used. When time is provided, it is assumed that the date has full resolution, which affects some regions FX rate calculation - Serbia for example.No
    order_date_typestring'timestamp' means that an order date was captured with a full timestamp and can be applied to an FX source which distinguishes time of the day. Empty value or 'day' means that only day information is present.No
    supply_datestringSupply date in yyyy-MM-dd format.No
    confirm_timestampstringDate and time of transaction confirmation.No
    create_timestampstringDate and time of transaction creation.No
    buyer_emailstringBuyer's declared email address.No
    buyer_namestringBuyer's name - first name and last name or company name.No
    tax_timezonestringTimezone name for tax transaction.No
    tax_country_codestringTwo-letter ISO country code, e.g. FR. This code applies to detected/set country for transaction, but can be set using manual mode.No
    force_country_codestringForce country code instead of applying detection. Only available when private token and manual mode is used.No
    tax_deductedbooleanTrue if the transaction is deducted from tax and no tax is applied (it is untaxed). Either set automatically when VAT number validates with VIES correctly, but can also be provided in manual mode.No
    tax_entity_namestringTo which entity is the tax due.No
    tax_entity_additional_idstringTax entity additional id.No
    total_amountnumberTotal amount of transaction.No
    amountnumberAmount of transaction without tax.No
    tax_amountnumberTax amount of transaction.No
    deducted_tax_amountnumberHow much tax has been deducted.No
    refunded_total_amountnumberTotal amount refunde (including tax).No
    refunded_tax_amountnumberRefunded tax amount.No
    invoice_addressobjectInvoice address.No
        freeform_addressstringFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.No
        building_numberstringBuilding number.No
        street_namestring Street name.No
        address_detailstringAddress details - for example apartament number.No
        citystringCity name.No
        postal_codestringPostal code.No
        regionstringRegion, for United States - state code - e.g. NJ.No
        countrystring2-letter ISO country code.No
    invoice_numberstringInvoice number.No
    invoice_datestringInvoice date of issue.No
    invoice_placestringInvoice place of issue.No
    invoice_image_urlstringInvoice image URL - provided by Taxamo.No
    fully_informativebooleanSet to true if transaction has only informative lines.No
    kindstringTransaction kind: eu-b2c, eu-b2b, domestic, untaxedNo
    tax_supportedbooleanIs tax calculation supported for a detected tax location?No
    countriesobjectMap of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.No
        by_ipobjectCountry detected by IPNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        forcedobjectCountry forced by paramtersNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_billingobjectCountry detected by billing country codeNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_ccobjectCountry detected by credit card number prefixNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_tokenobjectCountry detected from SMS tokenNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        detectedobjectCountry detected from other evidenceNo
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        self_declarationobjectSelf declared country as evidence.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant.No
            codenumstringCountry ISO 3-digit code.No
            namestringCountry name.No
            code_longstringThree letter ISO country code.No
            ccn3stringCountry ISO 3-digit code.No
            codestringTwo letter ISO country code.No
            cca2stringTwo letter ISO country code.No
            cca3stringThree letter ISO country code.No
            callingCodestring[]List of phone number calling codes.No
            currencystring[]List of currencies.No
            tax_number_country_codestringVAT number country code. Important for Greece.No
            tax_supportedbooleanTrue if tax calculation supported for this country.No
            tax_regionstringTax region code - e.g. EU, US, NO, JP...No
    buyer_ipstringIP address of the buyer in dotted decimal (IPv4) or text format (IPv6).No
    buyer_tax_numberstring Buyer's tax number - EU VAT number for example. If using EU VAT number, it is possible to provide country code in it (e.g. IE1234567X) or simply use billing_country_code field for that. In the first case, if billing_country_code value was provided, it will be overwritten with country code value extracted from VAT number - but only if the VAT has been verified properly.No
    buyer_tax_number_normalizedstringBuyer's tax number - normalized form.No
    buyer_tax_number_validbooleanIf the buyer tax number has been provided and was validated successfully. Always true for domestic transactions (billing country same as merchant's country), tax number doesn't get validated in that case.No
    buyer_tax_number_format_validbooleanIf the buyer tax number has been checked for syntax and is correct. It does not determine if the transaction should be tax deducted.No
    tax_deductedbooleanIf the transaction is in a country supported by Taxamo, but the tax is not calculated due to merchant settings or EU B2B transaction for example.No
    billing_country_codestringBilling two letter ISO country code.No
    buyer_credit_card_prefixstringFirst 6 digits of buyer's credit card prefix.No
    evidenceobjectTax country of residence evidence.No
        by_ipobjectCountry detected by IPNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        forcedobjectCountry forced by paramtersNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        guessed_from_ipobjectCountry guessed from IP due to lack of other evidenceNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_billingobjectCountry detected by billing country codeNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_ccobjectCountry detected by credit card number prefixNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tax_numberobjectCountry detected from EU TAX numberNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_tokenobjectCountry detected from SMS tokenNo
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_payment_methodobjectCountry detected by payment method.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        by_2003_rulesobjectUsed when merchant uses 2003 EU VAT rules.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        self_declarationobjectSelf declared country as evidence. Requires merchant setting to be active.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
        other_commercially_relevant_infoobjectAdditional evidence held by the merchant. Can be used only with a private token.No
            usedbooleanIf the evidence was used to match the actual country.No
            resolved_country_codestringCountry code that was resolved using this evidence.No
            evidence_typestringType of evidence.No
            evidence_valuestringValue provided as evidence - for example IP address.No
    additional_currenciesobjectAdditional currency information - can be used to receive additional information about invoice in another currency.No
        invoiceobjectInvoicing currency information.No
            currency_codestring3-letter ISO currency code.No
            amountnumberAmount (w/o TAX) in designated currency.No
            tax_amountnumberTax amount in designated currency.No
            fx_ratenumberForeign exchange rate used in calculationNo
            fx_datestringDate to use when calculating invoice FX rate. Defaults to transaction's order date.No
            total_amountnumberTotal amount in designated currency.No
    original_transaction_keystringUse data and evidence from original transaction. Tax will be re-calculated, but evidence won't be re-checked. This parameter is taken into account only when 'manual' flag is raised.No
    verification_tokenstringVerification tokenNo
    force_country_codestringTwo-letter ISO country code, e.g. FR. Use it to force country code for tax calculation.No
    custom_fieldsarrayCustom fields, stored as key-value pairs. This property is not processed and used mostly with Taxamo-built helpers.No
        keystringField's key.No
        valuestringField's value.No
    sourcestringTransaction source software - e.g. pluginNo
    external_keystringTransaction external keyNo
    tax_dataobjectTax additional information - e.g. US sales tax exemption certificate data.No
        us_tax_exemption_certificateobjectUS sales tax exemption certificate.No
            certificate_idstringThe exemption certificate number.No
            detailobjectUS tax exemption ertificate detail.No
                exempt_statesList of states where the certificate is valid.Yes
                single_purchasebooleanSet to true if this certificate is valid for single purchase only.No
                single_purchase_order_identifierstringPurchase/order identifier for single purchase.No
                purchaser_first_namestringPurchaser's first name.Yes
                purchaser_last_namestringPurchaser's last name.Yes
                purchaser_titlestringPurchaser's title.No
                purchaser_address1stringPurchaser's first address line.Yes
                purchaser_address2stringPurchaser's second address line.No
                purchaser_zipstringPurchaser's zip code.Yes
                purchaser_citystringPurchaser's city.Yes
                purchaser_statestringPurchaser's state.Yes
                purchaser_tax_idobjectPurchaser's TAX ID.Yes
                    tax_id_typestringTax id type.Yes
                    tax_idstringTax IDNo
                    state_of_issuestringState of issueNo
                purchaser_business_typestringPurchaser business type.Yes
                purchaser_business_type_other_valuestringIf business type is other, a short description must be provided.No
                purchaser_exemption_reasonstringThe reason for exemption reason.Yes
                purchaser_exemption_reason_valuestringThe value of exemption reason.Yes
    notestringAdditional note related to transaction state - for example if the transaction was created in a 'catch-all' mode or the VAT number re-check for subscriptions has failed.No
    tax_number_servicestringTax number service identifier - if available for a given region and the region is enabled.No
    commentsstringAdditional information about the transaction - for example if the evidence has been amended.No
    sub_account_idstringSub account identifier.No
    warningsarrayWarnings for the transaction process, usually related to contacting B2B validation service.No
        typestringType of error.No
        messagestringError detailsNo
    control_flagsarrayControl flags, stored as key-value string pairs. Possible flags (keys): "b2b-number-service-timeoutms", "b2b-number-service-expiry-days", "b2b-number-service-on-error" (value "accept"). Region code can be appended to all of the keys, e.g. "b2b-number-service-timeoutms-EU". No
        keystringFlag's key.No
        valuestringFlag's value.No

Authentication

Private token is required. It can be provided as:

  • Query string parameter, for example: GET /api/v1/transactions?private_token=SamplePrivateTestKey1&...
  • As an HTTP header, such as: Private-Token: SampleTestPrivateKey1

Response codes

  • 200 - Success
  • 400 - Validation failed
  • 401 - Authentication error
  • 500 - Unexpected error

Example call

$ curl -H "Private-Token: SamplePrivateTestKey1" \
 'https://api.taxamo.com/api/v1/transactions?tax_country_code=IE&offset=1&limit=2'
TaxamoApi taxamoApi = new TaxamoApi("SamplePrivateTestKey1");

ListTransactionsOut result;


try {
    result = taxamoApi.listTransactions(null,null,"IE",null,1,null,null,null,null,2);
} catch (ApiException ae) {
    // handle exception
}

Example response

{
   "transactions" : [
      {
         "tax_region" : "EU",
         "create_timestamp" : "2016-10-21T11:13:04Z",
         "key" : "TVkoAAAABbqWsHyiY0pNYCfhARgk",
         "buyer_ip" : "109.129.135.236",
         "custom_id" : "customId1",
         "status" : "C",
         "refunded_tax_amount" : 0,
         "amount" : 22,
         "test" : true,
         "currency_code" : "EUR",
         "transaction_lines" : [
            {
               "custom_id" : "1",
               "quantity" : 1,
               "line_key" : "MHeD7qijA4G_EqYH",
               "tax_rate" : 0,
               "tax_name" : "European VAT",
               "tax_amount" : 0,
               "line_num" : 1,
               "total_amount" : 22,
               "product_type" : "default",
               "num" : null,
               "amount" : 22,
               "deducted_tax_amount" : 0,
               "unit_price" : 22
            }
         ],
         "buyer_tax_number_valid" : true,
         "order_date" : "2016-10-21T11:11:50Z",
         "buyer_credit_card_prefix" : "424242424",
         "additional_currencies" : {},
         "source" : "Stripe webhook in Taxamo",
         "update_timestamp" : 1477048386857,
         "total_amount" : 22,
         "fully_informative" : false,
         "tax_amount" : 0,
         "kind" : "eu-b2b",
         "manual" : true,
         "invoice_place" : "Tralee232323",
         "confirm_timestamp" : "2016-10-21T11:13:06Z",
         "custom_fields" : [
            {
               "key" : "stripe-customer-id",
               "value" : "cus_5mJjLVSJQjMmnK"
            },
            {
               "key" : "stripe-token",
               "value" : "tok_15al5d2qiE2goZc6kQN795Zg"
            },
            {
               "value" : "some value",
               "key" : "some-custom-key"
            }
         ],
         "tax_deducted" : true,
         "billing_country_code" : "IE",
         "buyer_email" : "test@taxamo.com",
         "buyer_name" : "ASTERION SOFTWARE LIMITED",
         "description" : "Evidence placeholder for Stripe subscription",
         "evidence" : {
            "by_tax_number" : {
               "evidence_type" : "by-tax-number",
               "resolved_country_code" : "IE",
               "used" : true,
               "evidence_value" : "IE6437116J"
            },
            "by_ip" : {
               "evidence_value" : "109.129.135.236",
               "used" : false,
               "resolved_country_code" : "BE",
               "evidence_type" : "by-ip"
            },
            "by_cc" : {
               "evidence_type" : "by-cc",
               "resolved_country_code" : "BE",
               "used" : false,
               "evidence_value" : "424242424"
            },
            "by_billing" : {
               "evidence_value" : "IE",
               "resolved_country_code" : "IE",
               "used" : true,
               "evidence_type" : "by-billing"
            }
         },
         "original_transaction_key" : "TksMAAAABOresHwQZaepU8ELNraw",
         "tax_country_code" : "IE",
         "invoice_address" : {
            "freeform_address" : "GLENACRE ,LACKENROE ,GLANMIRE ,CO.CORK",
            "country" : "IE"
         },
         "refunded_total_amount" : 0,
         "deducted_tax_amount" : 0,
         "tax_timezone" : "GB",
         "tax_number_service" : "vies",
         "buyer_tax_number" : "IE6437116J"
      },
      {
         "refunded_total_amount" : 0,
         "invoice_address" : {},
         "tax_number_service" : "vies",
         "tax_timezone" : "GB",
         "deducted_tax_amount" : 0,
         "billing_country_code" : "IE",
         "custom_fields" : [
            {
               "key" : "stripe-subscription-id",
               "value" : "sub_8H1LGcEuNmRCHB"
            },
            {
               "key" : "stripe-customer-id",
               "value" : "cus_8H1LVCm0c2OVMj"
            },
            {
               "value" : "tok_180TIn2qiE2goZc6IbGhSxVb",
               "key" : "stripe-token"
            },
            {
               "value" : "taxamo_test_b2c",
               "key" : "taxed-plan-id"
            },
            {
               "key" : "untaxed-plan-id",
               "value" : "taxamo_test_b2b"
            }
         ],
         "confirm_timestamp" : "2016-10-21T10:33:14Z",
         "invoice_place" : "London, Some where",
         "kind" : "eu-b2c",
         "manual" : true,
         "tax_amount" : 2.24,
         "fully_informative" : false,
         "tax_country_code" : "IE",
         "original_transaction_key" : "TcWEAAAABPLqsHy3CyBJXELTRGco",
         "description" : "Taxamo B2C Test plan",
         "evidence" : {
            "by_billing" : {
               "evidence_type" : "by-billing",
               "resolved_country_code" : "IE",
               "used" : true,
               "evidence_value" : "IE"
            },
            "by_cc" : {
               "evidence_value" : "424242",
               "resolved_country_code" : "BE",
               "used" : false,
               "evidence_type" : "by-cc"
            },
            "by_ip" : {
               "evidence_type" : "by-ip",
               "used" : true,
               "resolved_country_code" : "IE",
               "evidence_value" : "52.48.232.115"
            }
         },
         "order_date" : "2016-10-21T10:31:56Z",
         "transaction_lines" : [
            {
               "tax_amount" : 2.24,
               "line_key" : "CfWpHZTqNtfQNlRP",
               "tax_name" : "European VAT",
               "tax_rate" : 23,
               "quantity" : 1,
               "custom_id" : "1",
               "unit_price" : 9.76,
               "num" : null,
               "description" : "Taxamo B2C Test plan",
               "amount" : 9.76,
               "line_num" : 1,
               "total_amount" : 12
            }
         ],
         "total_amount" : 12,
         "update_timestamp" : 1477045994604,
         "source" : "Stripe webhook in Taxamo",
         "buyer_credit_card_prefix" : "424242",
         "additional_currencies" : {},
         "buyer_ip" : "52.48.232.115",
         "key" : "TrOYAAAAB1IOsHyiY_2dYCe7ov4o",
         "create_timestamp" : "2016-10-21T10:33:12Z",
         "tax_region" : "EU",
         "currency_code" : "EUR",
         "amount" : 9.76,
         "test" : true,
         "refunded_tax_amount" : 0,
         "status" : "C"
      }
   ]
}

result: class ListTransactionsOut {
  transactions: [class Transactions {
  invoiceDate: null
  invoiceAddress: null
  manual: null
  buyerCreditCardPrefix: null
  customFields: null
  additionalCurrencies: null
  buyerTaxNumber: null
  customId: null
  deductedTaxAmount: 0
  taxCountryCode: IE
  forceCountryCode: null
  taxAmount: 23.00
  taxTimezone: GB
  buyerEmail: null
  originalTransactionKey: null
  test: true
  status: N
  createTimestamp: 2015-02-11T12:55:08Z
  totalAmount: 123.00
  taxEntityName: null
  buyerIp: 109.77.196.88
  refundedTaxAmount: null
  countries: null
  invoicePlace: Killorglin232323
  verificationToken: null
  taxDeducted: null
  buyerName: null
  confirmTimestamp: null
  evidence: class Evidence {
  by2003Rules: null
  byPaymentMethod: null
  byTaxNumber: null
  byCc: null
  byIp: class EvidenceSchema {
  used: true
  resolvedCountryCode: IE
  evidenceType: by-ip
  evidenceValue: 109.77.196.88
}
  byToken: null
  byBilling: class EvidenceSchema {
  used: true
  resolvedCountryCode: IE
  evidenceType: by-billing
  evidenceValue: IE
}
  guessedFromIp: null
  forced: null
}
  amount: 100.00
  customData: null
  billingCountryCode: IE
  taxSupported: null
  invoiceNumber: null
  currencyCode: EUR
  refundedTotalAmount: null
  description: null
  supplyDate: null
  transactionLines: [class TransactionLines {
  customFields: []
  additionalCurrencies: null
  customId: line1
  deductedTaxAmount: null
  productType: default
  quantity: 1
  taxAmount: 23.00
  unitPrice: 100.00
  unitOfMeasure: null
  totalAmount: 123.00
  taxRate: 23
  refundedTaxAmount: null
  lineKey: 9a-ZDtUldpBrN6nj
  amount: 100.00
  id: null
  refundedTotalAmount: null
  informative: null
  description: null
  productCode: null
  supplyDate: null
  taxName: European VAT
}]
  orderDate: 2015-02-11T12:55:08Z
  key: Tw-kAAAABjMmsHxghVtdU21EsxOw
},
  class Transactions {
  invoiceDate: null
  invoiceAddress: null
  manual: null
  buyerCreditCardPrefix: null
  customFields: null
  additionalCurrencies: null
  buyerTaxNumber: null
  customId: null
  deductedTaxAmount: 0
  taxCountryCode: IE
  forceCountryCode: null
  taxAmount: 23.00
  taxTimezone: GB
  buyerEmail: null
  originalTransactionKey: null
  test: true
  status: N
  createTimestamp: 2015-02-11T12:39:42Z
  totalAmount: 123.00
  taxEntityName: null
  buyerIp: 109.77.196.88
  refundedTaxAmount: null
  countries: null
  invoicePlace: Killorglin232323
  verificationToken: null
  taxDeducted: null
  buyerName: null
  confirmTimestamp: null
  evidence: class Evidence {
  by2003Rules: null
  byPaymentMethod: null
  byTaxNumber: null
  byCc: null
  byIp: class EvidenceSchema {
  used: true
  resolvedCountryCode: IE
  evidenceType: by-ip
  evidenceValue: 109.77.196.88
}
  byToken: null
  byBilling: class EvidenceSchema {
  used: true
  resolvedCountryCode: IE
  evidenceType: by-billing
  evidenceValue: IE
}
  guessedFromIp: null
  forced: null
}
  amount: 100.00
  customData: null
  billingCountryCode: IE
  taxSupported: null
  invoiceNumber: null
  currencyCode: EUR
  refundedTotalAmount: null
  description: null
  supplyDate: null
  transactionLines: [class TransactionLines {
  customFields: []
  additionalCurrencies: null
  customId: line1
  deductedTaxAmount: null
  productType: default
  quantity: 1
  taxAmount: 23.00
  unitPrice: 100.00
  unitOfMeasure: null
  totalAmount: 123.00
  taxRate: 23
  refundedTaxAmount: null
  lineKey: RNQtB4ewsXHmG3if
  amount: 100.00
  id: null
  refundedTotalAmount: null
  informative: null
  description: null
  productCode: null
  supplyDate: null
  taxName: European VAT
}]
  orderDate: 2015-02-11T12:39:42Z
  key: TKrcAAAABM4WsHxghcEpU202Ozoc
}]}