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:

Field	Details	Description
`confirm_timestamp`	Type: String	Date and time of transaction confirmation.
`fully_informative`	Type: Boolean	Set to true if transaction has only informative lines.
`deducted_tax_amount`	Type: Number	The amount of tax which has been deducted. For example, due to reverse-charge mechanism for B2B transactions.
`order_date_type`	Type: String	`timestamp` 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_date`	Type: String	Invoice date of issue.
`create_timestamp`	Type: String	Date 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_date`	Type: String	Supply 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_flags`		Control 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_address`		See Address Schema.
`buyer_tax_number_valid`	Type: Boolean	If 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_supported`	Type: Boolean	Is tax calculation supported for a detected tax location?
`tax_data.us_tax_exemption_certificate`		See US Tax Exemption Certificate Schema.
`transaction_lines`		Transaction 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_interactions`		See 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_fields`		Custom 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_data`		Shipment country data.
`shipment_country_data.tax_option`	Type: String	Tax option selected for the shipment country.
`refunds`		See 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.
`countries`		See 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.
`warnings`		Warnings 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_currencies`		See Additional Currency Schema.
`ship_to_address`		See 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.
`evidence`		Tax 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.