Important Fields

Read about some of the more significant fields that you can use when you model your requests or that may contain information that is returned by the API.

Main Fields

The main fields describe the transaction in general and are used in the majority of cases. These fields include the following:

Field	Description
`currency_code`	Required for each transaction, a 3-letter ISO code for the currency used. Examples: `EUR`, `USD`, `CNY`.
`order_date`	The sale date, in the `yyyy-MM-dd` format. For example `2016-12-31`. For Taxamo Assure customers, this date is not used. Instead, the current date in the GMT timezone is used. For Vertex for e-Commerce and Advantage Plus customers, the user (merchant's) timezone is used.
`buyer_email`	The buyer's email address. It can be used for invoice image delivery.
`test`	If this is set to `true`, the transaction has been created using the TEST mode token.
`key`	A unique transaction identifier that is generated by the service.
`amount`	The base amount, not including taxes.
`total_amount`	The total amount, including taxes.
`tax_amount`	The sum of taxes. This is generated by the service.
`sub_account_id`	If this is set, this transaction has the VAT/GST obligation taken over by Taxamo.

Location Evidence Fields

For each evidence kind, the evidence_value field should be provided. If the evidence resolves correctly, the service will return updated information for each piece of evidence. This information will contain the following fields:

Field	Description
`evidence[by_tax_number].evidence_value`	The customer's Tax ID such as a VAT ID. The ID is checked by Vertex Validator and a validation result is returned.
`evidence[by_ip].evidence_value`	The customer's IP address used to make the purchase.
`evidence[by_cc].evidence_value`	The customer's credit card BIN (Bank Identification Number).
`evidence[by_billing].evidence_value`	The customer's billing country, a 2-letter ISO code.
`evidence[by_payment_method].evidence_value`	If the payment method has provided country evidence, please specify the 2-letter ISO country code here (for example GB)
`evidence[by_self_declaration].evidence_value`	If the customer has provided a self-declared country code, please specify the 2-letter ISO country code here (for example GB)
`evidence[ other_commercially_relevant_info].evidence_value`	If the payment method has provided country evidence, please specify the 2-letter ISO country code here (for example GB).

Tax Information Fields

Tax information is returned in responses sent from the API in the following fields:

Field	Description
`tax_deducted`	If set to true, the transaction will have no tax applied even though it is created in a taxable region.
`tax_country_code`	Resolved tax country code as derived by the service.
`tax_supported`	Set to true if tax calculation is supported in the location detected.
`kind`	The type of transaction. This is generated by the service.
`buyer_tax_number_valid`	If set to `true`, the provided `buyer_tax_number` has been validated. If set to `false`, the number has been checked but it has been deemed invalid. If present and set to `null`, the check has failed. For example, the Tax Authority's system was offline. If not present, the tax number wasn't checked.

Transaction lines

All of the sale elements need to be provided as transaction lines. The most commonly used fields on each item in transaction_lines[] are:

Field	Description
`custom_id`	This is required for each line. The value needs to be unique transaction-wide.
`line_key`	Line key identifier generated by the service.
`amount`, `total_amount`, `unit_price`	Amount fields, either `amount`, `unit_price` or `total_amount` has to be provided. Other values are calculated from the highest ranking field provided.
`quantity`	Number of items in the transaction line. Defaults to `1`.
`tax_amount`	The tax amount that is applied.
`tax_rate`	The tax rate (in percents) applied to this transaction line. Provided by Vertex.
`tax_name`	The name of the tax, generated by the service.
`product_type`	Defaults to `default`. Some product types might have different tax rates in different regions.
`description`	The description field will be shown on the standard invoice template.

Custom/descriptive fields

Custom/descriptive field options include:

Field	Description
`custom_id`	Custom identifier of a transaction.
`customer_id`	Customer's ID.
`description`	transaction/transaction line description.
`custom_fields`	An array of objects with `key` and `value` attributes. Can be set on either the transaction or transaction line level.

Invoice information

Fields used to populate invoice information include:

Field	Description
`buyer_name`	Buyer's name.
`invoice_address`	invoice address to be displayed on the invoice.
`invoice_number`	The invoice number, that is generated by the service.
`invoice_image_url`	The invoice HTML image URL, that is generated by the service.