JavaScript SDK

The JavaScript SDK wraps the Tamio Transactions API so you can create transactions, collect payment details, and accept payments in any currency your account supports. It works with all connected payment providers (Stripe, Mollie, Revolut, GoCardless, etc.).

Even if you create transactions by calling the REST API directly, you can still use the SDK to render payment forms on the client side.

Getting Started

Step 1: Load the SDK on your page

// 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 one in the Tamio dashboard under Settings > Developers.

var tamio = new Tamio('your-publishable-token-here');

Create Transaction

Call createTransaction(options = {}) with a product list and customer info. On success, it returns a transaction object.

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 available options for createTransaction are documented at the Create Transaction endpoint.

Finalise Transaction

When the customer is ready to pay, call finaliseTransaction(transaction_id, options = {}, container_id, styles = {}). By default, the first available payment method is used.

You can pick a specific gateway. The available payment methods for a transaction are returned when you create it.

tamio.finaliseTransaction(
    'some-transaction-uuid',
    { payment: 'revolut' },
    'my_div'
);

With an instalment plan (plan IDs come from the Create Transaction response):

tamio.finaliseTransaction(
    'some-transaction-uuid',
    {
        payment: 'instalments',
        plan: 'plan-uuid'
    },
    'my_div'
);

Depending on the payment method, the transaction either finalises automatically or displays a call-to-action for the customer to complete the payment. No callback is provided due to the async nature of online payments.

Full options:

tamio.finaliseTransaction(
    // Transaction id
    'some-transaction-uuid',

    // Options
    {
        payment: 'instalments',
        plan: 'plan-uuid',

        // Update the shipping method
        shipping: 'some-shipping-uuid',

        // Where to redirect after order confirmation
        redirect: 'https://tamio.com'
    },

    // Container ID
    'my_div',

    // Styles (HEX or named colors: aqua, black, blue, etc.)
    {
      buttonColor: '#FFFFFF',
      buttonBorderColor: '#FFFFFF',
      buttonTextColor: 'blue',
      buttonBorderRadius: '16px', // 0px - 100px

      // Input fields (credit card number, etc.)
      inputBorderColor: '#FFFFFF',

      // Labels, spans, paragraphs
      labelColor: '#FFFFFF',
      labelBorderColor: '#FFFFFF'
    }
);

Styles are CSS rules applied to buttons, credit card fields, and radio fields rendered by third-party payment gateways. Some providers (Revolut Pay, Google Pay) don't allow DOM modifications, so styles may not always apply.

Transaction Updates

Switching between payment gateways can change the order total (payment-specific discounts, taxes, etc.). Listen for the transactionUpdated event to get the updated transaction object:

tamio.addEventListener('transactionUpdated', (e) => {
  console.log('Transaction Object: ', e.detail);
}, false);

Redirects

Each payment processor handles post-payment flow differently, which makes thank-you page redirects tricky. Pass a redirect URL in the finalise options and the SDK handles the rest.

The redirect URL receives these query parameters:

transaction_id — the transaction UUID
item_total — total cost of items
item_count — number of items purchased
total — the order total
customer_id — the customer UUID

Need more data on the redirect? Contact the Tamio team.

Warning: If your flow requires payment confirmation before showing the thank-you page, do not use the redirect feature. It is for order confirmation only, not payment confirmation.

Estimate Transaction

To preview order costs or available payment methods before creating a real transaction, use estimateTransaction(options = {}). It returns a full transaction object.

var params = {
  products: [
    { id: 'some-product-id', quantity: 6 },
    { name: 'My Product', price: 10 }
  ],
  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

Check whether a coupon code is valid before creating a transaction:

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

The SDK uses a whitelabeled API URL by default. If you want all requests to go through your own domain, pass a baseUrl when initialising:

var tamio = new Tamio('your-publishable-token-here', {
  baseUrl: 'https://api.yourdomain.com'
});