Connecting to Taxamo from PHP

Taxamo provides free, Swagger-codegen generated bindings to the RESTful API. Source code is available as a github repo: https://github.com/taxamo/taxamo-php.

The project is also used to report Taxamo PHP API related issues: https://github.com/taxamo/taxamo-php/issues.

Please also consult regression tests on example usage of the API.

Installation

Taxamo-php bindings are available as a Composer module, so merchants just need to add the following entry to composer.json file:

{
  "require": {
    "taxamo/taxamo-php": "2.*"
  }
}

And next run the following command:

composer.phar install #or composer install on Mac OS X

Finally, to import the required files, merchants can also use the autoload feature from Composer:

require_once('vendor/autoload.php');

Or just load the vendor/taxamo/taxamo-php/Taxamo.php file:

require_once('vendor/taxamo/taxamo-php/lib/Taxamo.php');

If not using Composer, merchants can just clone the https://github.com/taxamo/taxamo-php GitHub repository with any git client, for example:

git clone https://github.com/taxamo/taxamo-php

Next refer the Taxamo.php file – the actual path depends on the merchant’s project layout:

require_once('path/to/taxamo-php/Taxamo.php');

Setting up Taxamo API

To access the Taxamo API from PHP, merchants need to initialize it providing an access token and the endpoint url:

$taxamo = new Taxamo\Taxamo(
    new Taxamo\APIClient('your_private_key', 'https://api.taxamo.com'));

Pre-calculating tax

To invoke tax pre-calculation mechanism, the calculateTax() function needs to be used:

$transaction_line1 = new Taxamo\Input_transaction_line();
$transaction_line1->amount = 200;
$transaction_line1->custom_id = 'line1';

$transaction_line2 = new Taxamo\Input_transaction_line();
$transaction_line2->amount = 100;
$transaction_line2->custom_id = 'line2';
$transaction_line2->product_type = 'e-book';

$transaction = new Taxamo\Input_transaction();
$transaction->currency_code = 'USD';
 //propagate customer's IP address when calling API server-side
$transaction->buyer_ip = $_SERVER['REMOTE_ADDR'];
$transaction->billing_country_code = 'IE';
$transaction->buyer_credit_card_prefix = '516622';
$transaction->transaction_lines = array($transaction_line1, $transaction_line2);

$resp = $taxamo->calculateTax(array('transaction' => $transaction));

echo "Total amount: ".$resp->transaction->total_amount;

Please note, that when calling the API to calculate tax server-side, it is suggested to propagate the buyer’s IP address to Taxamo using the buyer_ip field. Otherwise, the Taxamo API will use a merchant’s server’s IP address as one of the pieces of evidence, which might not be very feasible.

Storing Taxamo transaction

To store a transaction, the createTransaction() function needs to be used:

$transaction_line1 = new Taxamo\Input_transaction_line();
$transaction_line1->amount = 200;
$transaction_line1->custom_id = 'line1';

$transaction_line2 = new Taxamo\Input_transaction_line();
$transaction_line2->amount = 100;
$transaction_line2->custom_id = 'line2';
$transaction_line2->product_type = 'e-book';

$transaction = new Taxamo\Input_transaction();
$transaction->currency_code = 'USD';
 //propagate customer's IP address when calling API server-side
$transaction->buyer_ip = $_SERVER['REMOTE_ADDR'];
$transaction->billing_country_code = 'IE';
$transaction->force_country_code = 'FR';
$transaction->transaction_lines = array($transaction_line1, $transaction_line2);

$resp = $taxamo->createTransaction(array('transaction' => $transaction));

echo "Transaction key: ".$resp->transaction->key;

Please note, that when calling the API to store a transaction server-side, it is suggested to propagate the buyer’s IP address to Taxamo using the buyer_ip field. Otherwise, the Taxamo API will use the merchant’s server’s IP address as one of the pieces of evidence, which might not be very feasible.

Confirming Taxamo transaction

The confirmTransaction() function allows to confirm the previously created transaction, making it available for the settlement:

$taxamo->confirmTransaction($resp->transaction->key, null);

It is possible to confirm and update the transaction at the same time:

$transaction = new Taxamo\Input_transaction();
$transaction->currency_code = 'CHF';
$transaction->buyer_name = 'Python tester #2';
$transaction->invoice_place = 'Test street #5';
$transaction->invoice_address = array('street_name' => 'Test street #4');
$transaction->transaction_lines = array($transaction_line1, $transaction_line2);

$taxamo->confirmTransaction($resp->transaction->key, array('transaction' => $transaction)); 

If we want to update the transaction without confirming it, the updateTransaction() function should be used.

Other operations

Please review the RESTful API documentation for a complete list of operations.