The following sections of this topic describe how different types of transaction use the API.

Business-to-Business (B2B) (Integrated Vertex Validator)

More information is provided in the Integrated Vertex Validator topic.

The process flow can be as follows. The exact steps can vary in the real world and depend on how the service was integrated with your store or applications:

1. Tax ID sent in Store Transaction request. For example, a Buyer enters Tax ID when purchasing a good on the merchant's store. They enter their Tax ID such as a VAT ID during the checkout. This is sent in the Store Transaction request.
2. Tax ID validated using the cache or the Tax Authority's database of Tax IDs. Other transaction details are processed. The Tax ID is sent to Vertex for e-Commerce in the buyer_tax_number or buyer_tax_numbers field of the Store Transaction request.
3. Vertex Validator validates the Tax ID: Vertex Validator validates the number. The level of the validation can vary from a syntax check to checking the validity of the ID according to the requirements of the applicable Tax Authority and your settings.
4. The validity status, transaction key and other information returned in the response.
5. Transaction Key is sent in the Confirm Transaction request.
6. The Transaction is confirmed and the invoice is sent by the inbuilt Vertex Invoice IQ component.

Digital goods

More information is provided in the Digital Goods topic.

The following graphic shows an example transaction processing flow for digital goods:

The steps are:

1. Buyer purchases digital goods on the merchant's store.
2. Transaction details including location evidence are sent in the Store Transaction request.
3. The service verifies the evidence and if successful, a transaction and transaction key is created. The transaction key is returned in the response.
4. Buyer confirms the purchase. The merchant implemented the Confirm Transaction request to be triggered once payment is confirmed. Here, the buyer confirms the payment and the Confirm Transaction request is sent to the service. This request is a URL that contains the transaction key that was generated in the previous step.
5. Transaction key sent to Vertex. The Confirm Transaction request is a URL that contains the transaction key that was generated in the previous step.
6. Transaction details returned.
7. The invoice is sent by the service.
8. Buyer receives invoice.

Standalone Vertex Validator

More information is provided in the Standalone Vertex Validator topic. The process flow varies depending on whether the cache is used or not.

Real time validation

The steps are as follows:

1. A Validate Tax Number request is sent to the service. The details are specified in the URL:

https://{service_uri}/api/v3/tax_numbers/ABCD12345/validate&country_code=DE&business_name=Franc%27s%20Flowers&cache_expiry_timeout_days=0&on_error=proceed'

2. The Tax ID is checked against the database for that country.
3. The database returns a result.
4. The result is returned in the response from the Validate Tax Number request. For example:

{
"invoice_address": {
"freeform_address": "---",
"country": "DE"
},
"buyer_tax_number": "123456789",
"tax_deducted": true,
"billing_country_code": "DE",
"buyer_tax_number_format_valid": true,
"warnings": null,
"buyer_tax_number_valid": true,
"buyer_tax_number_normalized": "123456789",
"buyer_name": "---"
}

Cached validation

The following diagram shows a typical process flow where the cache is set to 30 days:

The steps are as follows:

1. A Validate Tax Number request is sent to the service. The details are specified in the URL:

https://{service_uri}/api/v3/tax_numbers/ABCD12345/validate&country_code=DE&business_name=Franc%27s%20Flowers&cache_expiry_timeout_days=30&on_error=proceed'

2. The service checks the last 30 days of entries in the cache. If the cache does not contain the Tax ID, then the Tax Authority's database is checked (where this available for the country).
3. The result is returned in the Validate Tax Number response. For example:

{
"invoice_address": {
"freeform_address": "---",
"country": "DE"
},
"buyer_tax_number": "123456789",
"tax_deducted": true,
"billing_country_code": "DE",
"buyer_tax_number_format_valid": true,
"warnings": null,
"buyer_tax_number_valid": true,
"buyer_tax_number_normalized": "123456789",
"buyer_name": "---"
}

Invoices

More information is provided in the Vertex Invoice IQ topic.

The process flow is as follows. This is a simplified example and steps can vary substantially in a real implementation.

1. Buyer places goods in basket. The buyer places some goods in their basket but do not go to the checkout yet. The Store Transaction request is sent to the service and tax information and a transaction key is returned.
2. The service processes the transaction. The Store Transaction request is sent to the service.
3. Tax and other information is returned in the response to the Store Transaction request. The Transaction Key is also returned in the response.
4. The buyer completes the transaction. They complete checkout and purchase the goods.
5. The transaction is confirmed and the invoice is sent. A Confirm Transaction request is sent to Vertex for e-Commerce. This request uses the Transaction Key created in the previous step. The invoice is sent per settings to the buyer or merchant. An invoice is sent to the specified party, the email specified in the buyer_email field.
6. Buyer receives invoice.

Refunds

More information is provided in the Refunds topic.

Refunds are modelled using the Refund Transaction request. An example process flow is explained in the following graphic:

The example process flow is as follows. This is a simplified example. As the API is highly customizable, your deployment can vary in any number of ways.

1. Buyer requests refund: The buyer requests a refund by whatever means are allowed on the merchant's store.
2. Vertex for e-Commerce user issues refund to the buyer: You (the merchant/Vertex for e-Commerce user) decides this is a valid refund and issues the refund in their system that is in their e-commerce store or via their payment provider.
3. Refund Transaction request sent to Vertex for e-Commerce: You use the Refund Transaction request to integrate the refunds in Vertex for e-Commerce with your store or applications refunds. The request specifies details like the amounts and so on. This is processed and useful information is returned in the response. A credit note may also be sent to the liable party. This can be the buyer or seller and is dependent on other settings.
4. Refund issued in Vertex for e-Commerce: The request is processed by the service.
5. Refund details returned in the API response.
6. Credit sent per settings to buyer or seller: A credit note is sent to the email specified in the buyer_email field.
7. Buyer receives credit note.