Transaction Schema

The transaction schema contains the fields that represent a transaction. It also contains information that is returned by the API such as tax information.

The following table summarizes the available fields:

FieldDescription
confirm_timestampDate and time of transaction confirmation.
fully_informativeSet to true if transaction has only informative lines.
deducted_tax_amountThe amount of tax which has been deducted. For example, due to reverse-charge mechanism for B2B transactions.
order_date_type'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.
buyer_credit_card_prefixFirst 6 digits of buyer's credit card prefix. This takes precedence over 'evidence.by_cc' if both are supplied in the request. Note that 'evidence.by_payment_method' will be used as the payment country if supplied.
custom_dataCustom data related to transaction.
buyer_nameBuyer's name - first name and last name or company name.
invoice_dateInvoice date of issue.
create_timestampDate and time of transaction creation.
currency_codeCurrency code for transaction. For example EUR.
sub_account_idSub account identifier.
supply_dateSupply date in yyyy-MM-dd format.
buyer_tax_number_normalizedBuyer's tax number in a normalized form.
invoice_image_urlInvoice image URL. This value is returned in responses from the API.
keyThe Transaction Key that is generated by Vertex and returned in responses from the API.
tax_number_serviceTax number service identifier. If it is available for a given region and the region is enabled.
control_flagsControl 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, for example "b2b-number-service-timeoutms-EU".
buyer_tax_number_validIf 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.
verification_tokenSMS verification token. This takes precedence over 'evidence.by_token' if both are supplied.
noteAdditional 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.
tax_supportedIs tax calculation supported for a detected tax location?
tax_dataTax additional information. For example, US sales tax exemption certificate data.
us_tax_exemption_certificateUS sales tax exemption certificate. Used only with Vertex's TaxCloud integration.
transaction_linesTransaction lines.
buyer_tax_numberBuyer's tax number. For example, the EU VAT number for example. If valid this determines the tax country and other evidence is ignored. This takes precedence over 'evidence.by_tax_number' if both are supplied in the request. If using EU VAT number, it is possible to provide country code in it (for example 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 number has been verified properly.
external_keyTransaction external key
additional_interactionsInformation about additional interactions when necessary or available.
statusTransaction status: 'N' - new, 'C' - confirmed. Can use 'C' in when creating a transaction with a private token to create confirmed transaction, otherwise 'N' is default status. Not applicable when updating a transaction.
custom_fieldsCustom fields, stored as key-value pairs. This property is not processed and used mostly with Vertex-built helpers.
shipment_country_dataShipment country data.
tax_optionTax option selected for the shipment country.
force_country_codeTwo-letter ISO country code, for example FR. Use it to force country code for tax calculation.
countriesMap of countries calculated from evidence provided. This value is not stored and is available only upon tax calculation.
by_tokenCountry detected from SMS token
by_ccCountry detected by credit card number prefix
by_2003_rulesUsed when merchant uses 2003 EU VAT rules.
forcedCountry forced by parameters
by_ipCountry detected by IP
guessed_from_ipCountry guessed from IP due to lack of other evidence
other_commercially_relevant_infoAdditional evidence held by the merchant.
by_billingCountry detected by billing country code
by_tax_numberCountry detected from EU TAX number
detectedCountry detected from provided evidence
self_declarationSelf declared country as evidence.
invoice_numberInvoice number.
tax_country_codesComma separated list of tax country codes.
tax_engineTax engine used for the calculation.
product_classesProduct classes present in this transaction.
order_dateOrder 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.
external_unique_idExternal unique ID. It is advised to use secure and random identifiers in this field.
customer_idFree-form field for storing customer id.
kindTransaction kind: {region}-b2c, {region}-b2b, domestic, untaxed.
sourceTransaction source software. For example, plugin.
amountAmount of transaction without tax.
commentsAdditional information about the transaction - for example if the evidence has been amended.
buyer_ipIP address of the buyer in dotted decimal (IPv4) or text format (IPv6). This takes precedence over 'evidence.by_ip' if both are supplied.
buyer_emailBuyer's declared email address.
original_transaction_keyUse 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 true.
billing_country_codeBilling two letter ISO country code.
invoice_image_url_secretInvoice image URL secret URL. This is generated by the service.
custom_idCustom identifier provided upon transaction creation.
tax_amountTax amount of transaction.
tax_entity_additional_idTax entity additional ID.
warningsWarnings for the transaction process, usually related to contacting the Vertex Validator service.
additional_currenciesAdditional currency information. This can be used to receive additional information about invoice in another currency.
invoiceInvoicing currency information.
ship_to_addressShip to address.
used_for_tax_calculationIf the address has been used for tax calculation (digital only).
cityCity name.
postal_codePostal code.
countyCounty name
country_codeTwo-letter ISO country code. For example, FR.
street_nameStreet name.
regionRegion/State/Province. For example, a United States state code such as NJ.
address_detailAddress details such as apartment number.
freeform_addressFreeform address. Use when structured data is not available. Will be used in SAF-MOSS file if other fields are not provided.
building_numberBuilding number.
invoice_placeInvoice place of issue.
total_amountTotal amount of transaction.
tax_entity_nameTo which entity is the tax due.
evidenceTax country of residence evidence. This can be used in requests (use 'evidence_value' only) to pass evidence to Taxamo. Taxamo will fully populate each supplied evidence object in responses with the 'resolved_country_code' and 'used' fields.
by_tokenSMS verification token. Can be provided in requests but 'verification_token' will be used if both are provided.
by_ccCredit card number prefix. Can be provided in requests but 'buyer_credit_card_prefix' will be used if both are provided.
by_2003_rulesUsed when merchant uses 2003 EU VAT rules.
forcedForced country code. Present in the response if 'force_country_code' was provided in the request. Ignored if provided in the request.
by_payment_methodCountry determined by payment method. If provided in the request this takes precedence over country detected using 'evidence.by_cc' and 'buyer_credit_card_prefix'.
by_ipCustomer IP address. Can be provided in requests but 'buyer_ip' will be used if both are provided.
other_commercially_relevant_infoAdditional evidence held by the merchant. Can be used only with a private token.
by_billingBilling country code. Can be provided in requests but 'billing_country_code' will be used if both are provided.
by_tax_numberBuyer's tax number - EU VAT number for example. Can be provided in requests but 'buyer_tax_number' will be used if both are provided.
self_declarationCountry as self declared by the buyer. This is not used by default. Contact Taxamo support to enable it.
refunded_tax_amountRefunded tax amount.
manualWas the transaction created in manual mode - using private token. In manual mode, it is the merchant who calculates tax country and validates evidence. Manual mode must be used when using original_transaction_key field to link to a placeholder transaction.
tax_timezoneTimezone name for tax transaction.
descriptionTransaction description.
testWas this transaction created in test mode?
tax_deductedIf 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.
tax_country_codeTwo-letter ISO country code. For example FR. This code applies to detected/set country for transaction.
refunded_total_amountTotal amount refunded (including tax).