This topic is intended for users who are solely Vertex Invoice IQ customers. If you use one of the other products, this integration is likely already done and this topic does not apply to you. See Integrated Invoice IQ Deployments.

To integrate the service, you use the API. You can use the Store Transaction and Create Refund requests to integrate with your applications.

Settings

After the integration is complete, you can go to the Merchant Portal where you can adjust settings for your invoices under Settings > Invoicing.

API Integration

Transactions

You use the Store Transaction request to send transaction information to Vertex, where it is stored and an invoice is created.
To do so, use a POST operation and the following URL:

https://services.taxamo.com/api/v2/transactions/

You need to ensure that the status=C field is set. This means that the transaction is confirmed and an invoice will be issued.

You specify the details in the body of the request. For example:

$ curl -X 'POST' -H "Content-Type: application/json" -d \
 '{
      "transaction": {
          "transaction_lines": [
              {
                  "custom_id": "line1",
                  "amount": 100
              }
          ],
          "buyer_ip": "123.121.45.46",
	   “status”: “C”	
          "currency_code": "EUR",
          "billing_country_code": "BE",
          "buyer_credit_card_prefix": "424242424"
      },
      "private_token": "priv_***********"
  }' \
 'https://services.taxamo.com/api/v2/transactions'

Shipping

You can model shipping as a separate transaction call. For example:

        "transaction_lines": [
            {
                "description":"Acme Hammer",
                "amount": 10,
                "informative":true,
                "tax_rate":20,
                "custom_id": "1"
            },
            {
                "description":"Shipping",
                "amount": 2,
                "informative":true,
                "tax_rate":10,
                "custom_id": "2"
            }
        ]

Manual and Automated Location Determination

You may want to manually send your customers’ location information to Vertex or you may want Vertex to automatically derive this information from the location evidence.

Vertex Invoice IQ functions in one of the following modes to facilitate this:

• Manual: When this mode is set to manual, Vertex does not verify or derive customer location based on evidence. Instead, the location is specified by you (in the country_code field) in the request that is sent to the API.
• Automatic: When this mode is set to automatic, Vertex derives the customer’s location based on location evidence.

To enable manual mode, you need to add manual_mode=true to your requests. For example:

$ curl -X 'POST' -H "Content-Type: application/json" -d \
 '{
        “manual_mode”: “true”
        "transaction": {
          "transaction_lines": [
              {
                  "custom_id": "line1",
                  "amount": 100
              }
          ],
          "buyer_ip": "109.121.15.46",
	   “status”: “C”	
          "currency_code": "EUR",
          "billing_country_code": "BE",
          "buyer_credit_card_prefix": "424242424"
      },
      "private_token": "priv_***********"
  }' \
 'https://services.taxamo.com/api/v2/transactions'

Process Flow

The following graphic shows an example process flow for a standalone deployment:

The steps are as follows:

1. A Store Transaction request is sent to Invoice IQ. The request contains all the information that will be displayed on the invoice.
2. The service processes the invoice.
3. The invoice is sent to the buyer and the invoice details are returned in the Store Transaction request's response.

Post Transaction Processing

Refunds

You use the Create a refund request to issue refunds and credit notes.

To create a refund, you use a POST method and the following URL:

https://services.taxamo.com/api/v2/transactions/{key}/refunds/

where {key} is the Transaction Key of the transaction that you wish to refund.

For example:

$ curl -X 'POST' 'https://services.taxamo.com/api/v2/transactions/T60YAAAABteWsHwfho8xUz1l4fuo/refunds?line_key=SQ0Kuuvp4P9VnEzq&private_token=priv_***********&total_amount=100'

You can also include relevant information in the body of the request. This is summarized in the following table:

See Refunds Schema.