Transactions API
Javascript SDK

The Javascript SDK offered by Tamio acts as an efficient wrapper for the Tamio Transactions API. Its purpose is to provide a streamlined yet flexible approach to incorporating billing and payment capturing functionalities within any project. 
By leveraging the Javascript SDK, you have the power to create transactions, gather sensitive payment details, and accept payments in any currency supported by our platform. These functionalities are supported by all of our partnered payment providers, thus ensuring a wide range of options for your customers and reducing friction in the payment process.
Importantly, even if you are creating transactions outside of the Javascript SDK by directly calling the Transactions API, the SDK can still play a crucial role in your processes. It can be employed for payment rendering, adding another layer of flexibility to your operations. This allows you to benefit from the features of the SDK while maintaining direct interaction with the Transactions API for specific use-cases, providing a balance of convenience and control.
Getting Started
Step 1: Load the SKD on your page
HTML
// Production
<script src="https://pub.ox31.com/p/system/checkout.js"></script>

// Beta
<script src="https://pub.ox31.com/b/system/checkout.js"></script>
// Production
<script src="https://pub.ox31.com/p/system/checkout.js"></script>

// Beta
<script src="https://pub.ox31.com/b/system/checkout.js"></script>
﻿
Step 2: Initialise the SDK with your publishable developer token. You can create a token in the developers' section in your Tamio dashboard.
JS
var tamio = new Tamio('your-publishable-token-here');
var tamio = new Tamio('your-publishable-token-here');
﻿
﻿
Create Transaction
To create a transaction, call the createTransaction(options = {}) method with the required parameters, such as product id and customer information. If the response is successful, it will return a transaction object.
JS
var params = {
  products: [
    { id: 'some-product-id', quantity: 6 }, // Tamio Product
    { name: 'My Product', price: 10 } // Custom Invoice Item
  ],
  new_customer: {
    name: 'Mike Doe',
    email: '[email protected]',
    country: 'de'
  }
}

tamio.createTransaction(params).then((resp) => {
  if (resp.status === 200) {
    // Do something with resp.transaction
  } else {
   console.log(resp.error);
  }
});
var params = {
  products: [
    { id: 'some-product-id', quantity: 6 }, // Tamio Product
    { name: 'My Product', price: 10 } // Custom Invoice Item
  ],
  new_customer: {
    name: 'Mike Doe',
    email: 'mikedoe@tamio.com',
    country: 'de'
  }
}

tamio.createTransaction(params).then((resp) => {
  if (resp.status === 200) {
    // Do something with resp.transaction
  } else {
   console.log(resp.error);
  }
});
﻿
All the available options for the createTransaction method can be found at the Create Transaction﻿ endpoint.
﻿
Finalise Transaction
Once the customer is ready to complete their order, call the method finaliseTransaction(transaction_id, options = {}, container_id, styles = {}). By default, the first available payment willl be used when rendering.
You can also choose which payment gateway you would like to use. The available payments for a transaction are provided in the response when you Create a transaction﻿ 
JS
tamio.finaliseTransaction(
    'some-transaction-uuid',
    { payment: 'revolut' },
    'my_div'
);
tamio.finaliseTransaction(
    'some-transaction-uuid',
    { payment: 'revolut' },
    'my_div'
);
﻿
Example with an instalment plan. The available instalment plans and their ids are provided in the response when you Create a transaction﻿ 
JS
tamio.finaliseTransaction(
    'some-transaction-uuid',
    { 
        payment: 'instalments', 
        plan: 'plan-uuid'
    }, 
    'my_div'
);
tamio.finaliseTransaction(
    'some-transaction-uuid',
    { 
        payment: 'instalments', 
        plan: 'plan-uuid'
    }, 
    'my_div'
);
﻿
Depending on the payment method, the transaction will either finalise automatically or display a call-to-action so that the customer can complete their order. Due to the nature of online payments, no callback can be provided. 
And that's it! Once the customer makes the payment and we receive confirmation, the post-payment flow will be triggered.
  
Full Options
JS
tamio.finaliseTransaction(
    // Transaction id
    'some-transaction-uuid',
    
    // Options
    { 
        payment: 'instalments',
        plan: 'plan-uuid',
        
        // If you like the update the shipping method of the order.
        shipping: 'some-shipping-uuid',
        
        // Where to redirect upon order confirmation
        redirect: 'https://tamio.com'
    }, 
    
    // Container ID
    'my_div',
    
    // Styles
    // Colors can be in HEX format or one of the named options below:
    // "aqua", "black", "blue", "fuchsia", "gray", "green", "lime" 
    // "navy", "olive", "orange", "purple", "red", "silver", "teal"
    // "maroon", "white", "yellow"
    {
      buttonColor: '#FFFFFF',
      buttonBorderColor: '#FFFFFF',
      buttonTextColor: 'blue',
      buttonBorderRadius: '16px', // 0px - 100px
      
      // Applies to all input forms such as credit card number fields
      inputBorderColor: '#FFFFFF',
      
      // Applies to labels, spans and paragraphs
      labelColor: '#FFFFFF',
      labelBorderColor: '#FFFFFF'
    }
);
tamio.finaliseTransaction(
    // Transaction id
    'some-transaction-uuid',
    
    // Options
    { 
        payment: 'instalments',
        plan: 'plan-uuid',
        
        // If you like the update the shipping method of the order.
        shipping: 'some-shipping-uuid',
        
        // Where to redirect upon order confirmation
        redirect: 'https://tamio.com'
    }, 
    
    // Container ID
    'my_div',
    
    // Styles
    // Colors can be in HEX format or one of the named options below:
    // "aqua", "black", "blue", "fuchsia", "gray", "green", "lime" 
    // "navy", "olive", "orange", "purple", "red", "silver", "teal"
    // "maroon", "white", "yellow"
    {
      buttonColor: '#FFFFFF',
      buttonBorderColor: '#FFFFFF',
      buttonTextColor: 'blue',
      buttonBorderRadius: '16px', // 0px - 100px
      
      // Applies to all input forms such as credit card number fields
      inputBorderColor: '#FFFFFF',
      
      // Applies to labels, spans and paragraphs
      labelColor: '#FFFFFF',
      labelBorderColor: '#FFFFFF'
    }
);
﻿
Styles are CSS rules that get applied to the buttons, credit cards fields and radio fields rendered by third-party payment gateways.
Note that styles you provide might not always apply, as some payment providers such as Revolut Pay and Google Pay, do not allow modifications of their DOM elements.
﻿
Transaction Updates a﻿lpha﻿
When the customer switches between payment gateways, the total of the order might change. Some of the factors that might cause the total to change are: a) payment specific discounts and b) payment specific taxes.
You can listen to the transactionUpdated event in order to receive updates. 
JS
tamio.addEventListener('transactionUpdated', (e) => {
  console.log('Transaction Object: ', e.detail);
}, false);
tamio.addEventListener('transactionUpdated', (e) => {
  console.log('Transaction Object: ', e.detail);
}, false);
﻿
Redirects a﻿lpha﻿
Redirecting a customer to a thank you page during a checkout process is a tricky task, due to the differences in the flows of each payment processor. If you like the SDK to take care of this process, you can pass a URL to use as a redirect when finalising a transaction.
When the customer is redirected, you will also receive the following information as query parameters:
transaction_id: The id of the transaction
item_total: The total cost of the items in the order.
item_count: The total number of items purchased.
total: The order total.
customer_id: The id of the customer.
If you like to receive more information about the order during the redirect, get in touch with our team.
﻿
WARNING: If your thank you page flow requires the payment to be confirmed, do not use this feature. The redirect option is indented for order confirmation purposes only.
﻿
Estimate Transaction a﻿lpha﻿
If you like to estimate the cost of an order before generating a transaction or see which payment options will be available for a prospective customer, you can use the estimateTransaction(options = {}) method. The response provided is a complete Transaction Object﻿. For the available options see 
JS
var params = {
  products: [
    { id: 'some-product-id', quantity: 6 }, // Tamio Product
    { name: 'My Product', price: 10 } // Custom Invoice Item
  ],
  new_customer: {
    country: 'de'
  }
}

tamio.estimateTransaction(params).then((resp) => {
  if (resp.status === 200) {
    // Do something with resp.transaction
  } else {
   console.log(resp.errors[0]);
  }
});
var params = {
  products: [
    { id: 'some-product-id', quantity: 6 }, // Tamio Product
    { name: 'My Product', price: 10 } // Custom Invoice Item
  ],
  new_customer: {
    country: 'de'
  }
}

tamio.estimateTransaction(params).then((resp) => {
  if (resp.status === 200) {
    // Do something with resp.transaction
  } else {
   console.log(resp.errors[0]);
  }
});
﻿
Coupon Validation
In some cases, you might want to check if a coupon is valid before creating a transaction. For this use-case, you can use the validateCoupons method.
JS
Example Response
tamio.validateCoupons({ coupons: ['20%OFF'], 'products': ['some-product-id'], 'currency': 'EUR' }).then((resp) => {
  if (resp.status === 200) {
    // Do something with resp.coupons
  } else {
   console.log(resp.error);
  }
});
tamio.validateCoupons({ coupons: ['20%OFF'], 'products': ['some-product-id'], 'currency': 'EUR' }).then((resp) => {
  if (resp.status === 200) {
    // Do something with resp.coupons
  } else {
   console.log(resp.error);
  }
});
﻿
Whitelabel API Requests a﻿lpha﻿
By default the API URL used in the SDK is whitelabeled. Moreover, if you like to ensure a pure whitelabel experience, you can also configure the SDK to send all the API requests to your own Whitelabel domain like below.
JS
var tamio = new Tamio('your-publishable-token-here', 'https://api.your-whitelabel-domain-host');
var tamio = new Tamio('your-publishable-token-here', 'https://api.your-whitelabel-domain-host');
﻿
﻿
Abandon Transaction
WhiteLabel API
Javascript SDK

Getting Started

Create Transaction

Finalise Transaction

Transaction Updates alpha

Redirects alpha

Estimate Transaction alpha

Coupon Validation

Whitelabel API Requests alpha

Javascript SDK

Getting Started

Create Transaction

Finalise Transaction

Transaction Updates a﻿lpha﻿

Redirects a﻿lpha﻿

Estimate Transaction a﻿lpha﻿

Coupon Validation

Whitelabel API Requests a﻿lpha﻿

Transaction Updates alpha

Redirects alpha

Estimate Transaction alpha

Whitelabel API Requests alpha
