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:

FieldDescription
currency_codeRequired for each transaction, a 3-letter ISO code for the currency used. Examples: EUR, USD, CNY.
order_dateThe 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_emailThe buyer's email address. It can be used for invoice image delivery.
testIf this is set to true, the transaction has been created using the TEST mode token.
keyA unique transaction identifier that is generated by the service.
amountThe base amount, not including taxes.
total_amountThe total amount, including taxes.
tax_amountThe sum of taxes. This is generated by the service.
sub_account_idIf 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:

FieldDescription
evidence[by_tax_number].evidence_valueThe 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_valueThe customer's IP address used to make the purchase.
evidence[by_cc].evidence_valueThe customer's credit card BIN (Bank Identification Number).
evidence[by_billing].evidence_valueThe customer's billing country, a 2-letter ISO code.
evidence[by_payment_method].evidence_valueIf the payment method has provided country evidence, please specify the 2-letter ISO country code here (for example GB)
evidence[by_self_declaration].evidence_valueIf 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_valueIf 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:

FieldDescription
tax_deductedIf set to true, the transaction will have no tax applied even though it is created in a taxable region.
tax_country_codeResolved tax country code as derived by the service.
tax_supportedSet to true if tax calculation is supported in the location detected.
kindThe type of transaction. This is generated by the service.
buyer_tax_number_validIf 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:

FieldDescription
custom_idThis is required for each line. The value needs to be unique transaction-wide.
line_keyLine key identifier generated by the service.
amount, total_amount, unit_priceAmount fields, either amount, unit_price or total_amount has to be provided. Other values are calculated from the highest ranking field provided.
quantityNumber of items in the transaction line. Defaults to 1.
tax_amountThe tax amount that is applied.
tax_rateThe tax rate (in percents) applied to this transaction line. Provided by Vertex.
tax_nameThe name of the tax, generated by the service.
product_typeDefaults to default. Some product types might have different tax rates in different regions.
descriptionThe description field will be shown on the standard invoice template.

Custom/descriptive fields

Custom/descriptive field options include:

FieldDescription
custom_idCustom identifier of a transaction.
customer_idCustomer's ID.
descriptiontransaction/transaction line description.
custom_fieldsAn 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:

FieldDescription
buyer_nameBuyer's name.
invoice_addressinvoice address to be displayed on the invoice.
invoice_numberThe invoice number, that is generated by the service.
invoice_image_urlThe invoice HTML image URL, that is generated by the service.