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:

FieldDetailsDescription
confirm_timestampType: StringDate and time of transaction confirmation.
fully_informativeType: BooleanSet to true if transaction has only informative lines.
deducted_tax_amountType: NumberThe amount of tax which has been deducted. For example, due to reverse-charge mechanism for B2B transactions.
order_date_typeType: Stringtimestamp means that an order date was captured with a full timestamp and can be applied to an F/X source which distinguishes time of the day. An empty value or day means that only day information is present.
buyer_credit_card_prefix

Type: String

Max: 9

First 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_data

Type: String

Max: 256

Custom data related to transaction.
buyer_name

Type: String

Max: 512

Buyer's name - first name and last name or company name.
invoice_dateType: StringInvoice date of issue.
create_timestampType: StringDate and time of transaction creation.
currency_code

Type: String

Max: 3

Currency code for transaction. For example EUR.
sub_account_id

Type: String

Max: 64

Sub account identifier.
supply_dateType: StringSupply date in yyyy-MM-dd format.
buyer_tax_number_normalized

Type: String

Max: 256

Buyer's tax number in a normalized form.
invoice_image_url

Type: String

Max: 512

Invoice image URL. This value is returned in responses from the API.
key

Type: String

Max: 64

The Transaction Key that is generated by Vertex and returned in responses from the API.
tax_number_service

Type: String

Max: 64

Tax 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. Some possible flags (keys) are: b2b-number-service-timeoutms, b2b-number-service-expiry-days and b2b-number-service-on-error (value accept). Region codes can be appended to all of the keys, for example b2b-number-service-timeoutms-EU.
control_flags.{key}

Type: String

Max: 64

Key for control flag.
control_flags.{value}

Type: String

Max: 256

Value for control flag.
invoice_addressSee Address Schema.
buyer_tax_number_validType: BooleanIf 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_token

Type: String

Max: 64

SMS verification token. This takes precedence over 'evidence.by_token' if both are supplied.
note

Type: String

Max: 256

Additional 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_supportedType: BooleanIs tax calculation supported for a detected tax location?
tax_data.us_tax_exemption_certificateSee US Tax Exemption Certificate Schema.
transaction_linesTransaction lines.
buyer_tax_number

Type: String

Max: 256

Buyer'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.
buyer_tax_numbers

Type: String

Max: 256

Buyer's tax number. This field is used for Canada where multiple IDs need to be added.
external_key

Type: String

Max: 256

Transaction external key
additional_interactionsSee Additional Interactions.
status

Type: String

Transaction 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.
custom_fields.{key}

Type: String

Max: 64

Key for custom fields.
custom_fields.{value}

Type: String

Max: 256

Value for custom fields.
shipment_country_dataShipment country data.
shipment_country_data.tax_option

Type: String

Tax option selected for the shipment country.
refundsSee Refunds Schema.
force_country_code

Type: String

Max: 2

Two-letter ISO country code, for example FR. Use it to force country code for tax calculation.
countriesSee Countries.
invoice_number

Type: String

Max: 256

Invoice number.
tax_country_codes

Type: String

Max: 256

Comma separated list of tax country codes.
tax_engine

Type: String

Tax engine used for the calculation.
product_classes

Type: String

Max: 16

Product classes present in this transaction.
order_date

Type: String

Order 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 such as Serbia for example.
external_unique_id

Type: String

Max: 16

External unique ID. It is advised to use secure and random identifiers in this field.
customer_id

Type: String

Max: 256

Free-form field for storing customer id.
kind

Type: String

Max: 16

Transaction kind: {region}-b2c, {region}-b2b, domestic, untaxed.
source

Type: String

Max: 16

Transaction source software. For example, plugin.
amount

Type: Number

Amount of transaction without tax.
comments

Type: String

Max: 512

Additional information about the transaction - for example if the evidence has been amended.
buyer_ip

Type: String

Max: 256

IP address of the buyer in dotted decimal (IPv4) or text format (IPv6). This takes precedence over 'evidence.by_ip' if both are supplied.
buyer_email

Type: String

Max: 256

Buyer's declared email address.
original_transaction_key

Type: String

Max: 64

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 true.
billing_country_code

Type: String

Max: 2

Billing two letter ISO country code.
invoice_image_url_secret

Type: String

Max: 16

Invoice image URL secret URL. This is generated by the service.
custom_id

Type: String

Max: 256

Custom identifier provided upon transaction creation.
tax_amount

Type: Number

Tax amount of transaction.
tax_entity_additional_id

Type: String

Tax entity additional ID.
warningsWarnings for the transaction process, usually related to contacting the Vertex Validator service.
warnings.{type}

Type: String

The type of error.
warnings.{message}

Type: String

The message text.
additional_currenciesSee Additional Currency Schema.
ship_to_addressSee Address Schema.
invoice_place

Type: String

Max: 256

Address of issue for the invoice.
total_amount

Type: Number

Total amount for the transaction.
tax_entity_name

Type: String

To 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. See Location Evidence Schema.
refunded_tax_amount

Type: Number

Refunded tax amount.
manual

Type: Boolean

Indicates whether the transaction was 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_timezone

Type: String

Timezone name for tax transaction.
description

Type: String

Max: 512

Transaction description.
test

Type: Boolean

If set to true, it means the transaction was created in test mode.
tax_deducted

Type: Boolean

If 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_code

Type: String

Max: 2

Two-letter ISO country code. For example FR. This code applies to detected/set country for transaction.