Configuring the API Integration

❗️

Warning

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 does not apply to you.

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

Integrating 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": "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'

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'

Integrating 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 summarised in the following table:

Body Parameter

Description

private_token

Private token.

key

Transaction key.

line_key

Line identifier. If neither line key or custom ID is provided, the refund amount will be assigned to lines in order.

refund_timestamp

Refund timestamp in yyyy-MM-dd HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss'Z' format. No timezone conversion is applied.

amount

Amount (without tax) to be refunded. Either amount or total amount is required. In case of line key and custom id missing, only total_amount can be used.

total_amount

Total amount, including tax, to be refunded. Either amount or total amount is required. In case of line key and custom id missing, only total_amount can be used

refund_reason

Refund reason, displayed on the credit note.


Did this page help you?