tuna.js Library

The Tuna JavaScript libraries will allow you to tokenize customer information, collect sensitive card data and accept payments on your website. In this section, you will find all details, features and configurations to run these libraries at your web page.

To start using Tuna JavaScript library is as easy as including the tuna.js file in your checkout page. It is highly recommended that you do not store the js file at your server, for security reasons.

npm

It can also be added to your Node.js project with the npm package, which supports both JavaScript and TypeScript.

Integration methods

You can choose between using tuna.js to generate a complete payment form with tokenization and payment in a transparent way, or you can use it to just render the form and take care of tokenization while handling the payment API calls yourself at your backend system. Optionally you can use tuna.js solely to handle tokenization(in that case you need to be carefull not to send sensitive credit card data to your backend).

When you create a sessionID on your backend, you can choose to associate this session with just customer data or customer + order. This choice will vary according to the type of integration you'll use to connect to our Payment API, which can be either through backend or using Tuna JS.

When your backend places the payment API calls

Here you only need to send customer data when creating the sessionID.

When tuna.js places the payment API calls

Here the sessionID must have been generated including the order identifier. Keep in mind that since the payment is done before submitting the order to your backend, you must check that the order total matches with the total paid amount by either using a webhook or polling the payment status.

Getting started: Adding tuna.js

You can choose to use tuna.js to create a brand new checkout page or to link your checkout with Tuna connections. Below you'll see how to do the second option. To use the tuna.js to create a new checkout page and enjoy all facilities we provide, check it out here.

HTML

1<script src="https://js.tuna.uy/tuna-essentials.js"></script>

tuna.js V2

HTML

1<script src="https://storage.googleapis.com/tuna-statics/tuna-v2.js"></script>

tuna.js V2 CSS file

HTML

1<link rel="stylesheet" type="text/css" href="https://storage.googleapis.com/tuna-statics/components.min.css">

Initializing Tuna

Use the session ID generated by you backend to start Tuna.

Tuna (sessionID, env?, antifraudConfig?, integrateWithClickToPay?)

Call this method to initiate Tuna before performing any actions.

Method parameters

sessionIDstringREQUIRED

The sessionID is the public key you got using your personal data through Tuna Token API.

envstringOPTIONALDEFAULT:"production"

The environment name. Set env="sandbox" to use the sandbox environment of all related Tuna APIs

antifraudConfigarrayOPTIONALDEFAULT:null

An array of { key, value } object containing parameters to fill the antif-raud scripts.
Use keys with only lowercase alphanumeric characters

integrateWithClickToPayboolOPTIONALDEFAULT:undefined

An flag to indicate if tuna.js should interact with Click to Pay methods

Returns

object

The instance of Tuna object.

HTML

1const tuna = Tuna(sessionId);

Configuring antifrauds

Injects at the page the data collection scripts of all antifrauds providers linked to your Tuna account. You should use the antifraudConfig parameter at Tuna initialization to provide the following information about the customer session for each anti-fraud provider you use.

ClearSale	SiftScience	Konduto	CyberSource
sessionid	userid, sessionid	customerid	sessionid

Aditionally, you need to choose wich antifraud scripts you will inject. Do that by adding a another { key, value } object using the antifraud name as key and the antifraud public key as value. Look to the example bellow:

Javascript

1const tuna = Tuna(sessionId, [
2    { key: "sessionid", value: "6de61205-00ad-4068-b8bd-25a12ab9b305" },
3    { key: "customerid", value: "321" },
4    { key: "konduto", value: "konduto_key" },
5    { key: "cybersource", value: "cybersource_key" },
6]);

In the example above, were filled the requirements to inject the data collection scripts of Konduto and CyberSource antifraud

Initializing Click to Pay

Before using Click to Pay methods, you need to initialize the Click to Pay service. This method must be called before any other Click to Pay operations.

async initClickToPay ()

Initialize the Click to Pay service. This method must be called before using any Click to Pay functionality.

Returns

object

The initialization response from Click to Pay service.

Properties

Javascript

1// Initialize Click to Pay
2const initResult = await tuna.initClickToPay();
3console.log('Click to Pay initialized:', initResult);

Authenticating with Click to Pay

Use this method to authenticate a user with Click to Pay using their email address or mobile phone number.

async authenticateWithClickToPay (params)

Authenticate a user with Click to Pay service.

Method parameters

paramsobjectREQUIRED

The authentication parameters object.

Properties

Returns

object

The authentication response from Click to Pay service.

Properties

Javascript

1// Authenticate with email
2const authResult = await tuna.authenticateWithClickToPay({
3  loginType: 'EMAIL_ADDRESS',
4  identityValue: 'customer@example.com'
5});
6
7// Authenticate with phone number
8const authResult = await tuna.authenticateWithClickToPay({
9  loginType: 'MOBILE_PHONE_NUMBER',
10  identityValue: '+5511999999999'
11});

Accessing the Tuna tokenization connection

Use the Tuna tokenization connection through the tuna.js library to create PCI compliant card tokens.

HTML

1const tuna = Tuna(sessionId);
2const tokenizator = tuna.tokenizator();

async tokenizator.list ()

List saved card tokens to the given customer session ID.

Returns

object

The operation response is described here.

async tokenizator.generate (cardData)

Create a new credit card token entry

Method parameters

cardDataobjectREQUIRED

Object containing the credit card data to be tokenized.

Properties

Returns

object

The operation response is described here.

async tokenizator.delete (token)

Delete an already created card token.

Method parameters

tokenstringREQUIRED

The token associated to the credit card.

Returns

object

The operation response is described here.

async tokenizator.bind (token, cvv)

Binds a CVV with a token.

Method parameters

tokenstringREQUIRED

The token associated to the credit card.

cvvstringREQUIRED

The credit card CVV

Returns

object

The operation response is described here.

async tokenizator.encryptClickToPayCard (cardData)

Encrypt card data for Click to Pay transactions. This method encrypts the card information before it can be used with Click to Pay checkout.

Method parameters

cardDataobjectREQUIRED

Object containing the card data to be encrypted.

Properties

Returns

object

The encrypted card response object that can be used with checkoutWithClickToPayNewCard method.

Properties

Javascript

1// Encrypt card data for Click to Pay
2const tokenizator = tuna.tokenizator();
3const cardData = {
4  primaryAccountNumber: '5123456789012346',
5  panExpirationMonth: '12',
6  panExpirationYear: '2025',
7  cardSecurityCode: '123',
8  cardholderFirstName: 'John',
9  cardholderLastName: 'Doe',
10  billingAddress: {
11    name: 'John Doe',
12    line1: '123 Main Street',
13    city: 'New York',
14    state: 'NY',
15    zip: