Ionic SDK Lite

The Tonder Ionic SDK Lite is a solution for integrating our system into your mobile application. This solution ensures PCI DSS (Payment Card Industry Data Security Standard) by securely collecting and tokenizing sensitive data in the browser, without exposing your front-end infrastructure to any sensitive data.

This guide will walk you through all the steps, from installation and configuring our SDK to fit your application.

Installation

Tonder’s Ionic SDK can be installed using our npm package. Use the following command to install it:

npm i @tonder.io/ionic-lite-sdk

Requirements

To configure our SDK you need to add the following script tags to your HTML:

  <script src=https://openpay.s3.amazonaws.com/openpay.v1.min.js></script>
  <script src=https://openpay.s3.amazonaws.com/openpay-data.v1.min.js></script>

The code above is necessary to ensure a reliable connection to the payment processor.

You can also install each one with their respective npm packages.

Configuration

With Tonder’s SDK installed, and requirements met, you are ready to configure and use the SDK. The following step-by-step process takes you through everything, from starting a new instance, to performing a new transaction using the needed methods:

Import the Lite Checkout class

Start by adding the import statement for the LiteCheckout class in your file. Following you find an example of how to import the LiteCheckout:

  import { LiteCheckout } from "@tonder/ionic-lite-sdk"

The LiteCheckout object provides all the necessary methods to perform transactions. Essentially, LiteCheckout handles calls to Tonder services, allowing transactions to be performed without the need to integrate additional visual components.

Initialize Tonder's SDK Instance

Initialize Tonder’s Ionic SDK instance adding the following parameters:

Field	Description
`signal`	Signal from AbortController instance if it needs cancel the request.
`baseUrlTonder`	Tonder’s API base URL. -> Live server: `https://stage.tonder.io` -> Mock Server: `https://stoplight.io/mocks/tonder/tonder-api-v1-2/3152148`
`apiKeyTonder`	Your Tonder API key. You can find it in your Tonder dashboard.

  const baseUrlTonder = 'https://stage.tonder.io';
  const apiKeyTonder = '00d17d61e9240c6e0611fbdb1558e636ed6389db';

  const liteCheckout = new LiteCheckout({ 
    signal, 
    baseUrlTonder, 
    apiKeyTonder 
  });

Start Checkout Router Full method

Once you have initialized your liteCheckout instance, you need to call the startCheckoutRouterFull method and provide all the necessary data as an object. This method handles the entire checkout process, executing the transaction and returning the payment response. To start, call the startCheckoutRouterFullmethod providing the necessary information found below:

Parameter	Type	Description
`order`	`object`	Represents the details of each item in the order.
`total`	`number`	The total amount for the order. This should match the sum of the costs of items in the order.
`customer`	`object`	Information about the customer.
`skyflowTokens`	`object`	The details of the card to be used on the transaction.
`return_url`	`string`	URL to which the customer will be redirected after the checkout process is completed.
`isSandbox`	`boolean`	A boolean indicating if the transaction is being processed in a sandbox environment for testing purposes.
`metadata`	`object`	Optional additional data about the order that might be used for processing or tracking.
`currency`	`string`	The currency in which the transaction is conducted. Refer to the Currencies Reference page for details.

  const checkoutResponse = liteCheckout.startCheckoutRouterFull({ 
    order, 
    total, 
    customer, 
    skyflowTokens, 
    return_url, 
    isSandbox, 
    metadata, 
    currency
  });

Below you find the types for each startCheckoutRouterFull parameter, followed by an example code:

  type StartCheckoutFullRequest = {
      order: {
          items: Array<{
              description: string;
              quantity: number;
              price_unit: number;
              discount: number;
              taxes: number;
              product_reference: number;
              name: string;
              amount_total: number;
          }>;
      };
      total: number;
      customer: {
          name: string;
          lastname: string;
          email: string;
          phone: string;
      };
      skyflowTokens: {
          cardholder_name: string;
          card_number: string;
          cvv: string;
          expiration_year: string;
          expiration_month: string;
          skyflow_id: string;
      };
      return_url: string;
      isSandbox: boolean;
      metadata: any;
      currency: string;
  };

const checkoutRequest: StartCheckoutFullRequest = {
    order: {
        items: [
            {
                description: "High-quality wireless headphones",
                quantity: 2,
                price_unit: 199.99,
                discount: 20.00,
                taxes: 15.99,
                product_reference: 101234,
                name: "Wireless Headphones",
                amount_total: 395.96
            },
            {
                description: "Ergonomic wireless mouse",
                quantity: 1,
                price_unit: 50.00,
                discount: 5.00,
                taxes: 3.75,
                product_reference: 105678,
                name: "Wireless Mouse",
                amount_total: 48.75
            }
        ]
    },
    total: 444.71,
    customer: {
        name: "John",
        lastname: "Doe",
        email: "johndoe@example.com",
        phone: "+11234567890"
    },
    skyflowTokens: {
        cardholder_name: "John Doe",
        card_number: "4111111111111111",
        cvv: "123",
        expiration_year: "2024",
        expiration_month: "12",
        skyflow_id: "abcd-1234-xyz"
    },
    return_url: "https://example.com/checkout/complete",
    isSandbox: true,
    metadata: {
        campaign_id: "BF2024",
        notes: "Customer opted for gift wrapping."
    },
    currency: "USD"
};

Checkout Router Full response

As the startCheckoutRouterFull takes care of the full transaction process, it will return with the status of the transaction, along with all information regarding the process. The main information returned are as follows:

Field	Type	Description
`status`	`number`	The HTTP status code reflecting the outcome of the checkout process.
`message`	`string`	A message providing additional information about the response.
`psp_response`	`object`	An object containing detailed information from the payment service provider.
`transaction_status`	`string`	Status of the transaction as reported by the system.
`transaction_id`	`number`	A unique identifier for the transaction.
`payment_id`	`number`	A unique identifier for the payment linked to the transaction.
`provider`	`string`	The payment service provider(PSP) that is handling the transaction.
`next_action`	`object`	URLs to redirect the user for each possible situation.
`actions`	`Array<object>`	A list of possible actions related to the transaction.

Below you find the types of all parameters in the response:

type StartCheckoutResponse = {
    status: number;
    message: string;
    psp_response: {
        id: string;
        authorization: number;
        operation_type: string;
        transaction_type: string;
        status: string;
        conciliated: boolean;
        creation_date: string;
        operation_date: string;
        description: string;
        error_message?: string;
        order_id?: string;
        card: {
            type: string;
            brand: string;
            address?: string;
            card_number: string;
            holder_name: string;
            expiration_year: string;
            expiration_month: string;
            allows_charges: boolean;
            allows_payouts: boolean;
            bank_name: string;
            points_type: string;
            points_card: boolean;
            bank_code: number;
        };
        customer_id: string;
        gateway_card_present: string;
        amount: number;
        fee: {
            amount: number;
            tax: number;
            currency: string;
        };
        payment_method: {
            type: string;
            url: string;
        };
        currency: string;
        method: string;
        object: string;
    };
    transaction_status: string;
    transaction_id: number;
    payment_id: number;
    provider: string;
    next_action: {
        redirect_to_url: {
            url: string;
            return_url: string;
            verify_transaction_status_url: string;
        };
        iframe_resources?: {
            iframe: string;
        };
    };
    actions: Array<{
        name: string;
        url: string;
        method: string;
    }>;
};

Class Methods

After properly configuring your Lite Checkout instance, you have at your hand various methods to work with Tonder. Below you will find all the available methods, with an example of the data returned by each so you can understand how they work:

Get Business

Device Session ID

Customer

Order

Payment

Tokenization

Checkout Router

3DS Verification

Get Business

This method retrieves all the information about your business. Get details on branding, providers public keys, vault information, and more. To call it, do the following:

const merchantData = await liteCheckout.getBusiness();

The response to this method will be the following:

  {
    business: {
        pk: number,
        name: string,
        categories: [
          {
            pk: number,
            name: string
          }
        ],
        web: string,
        logo: string,
        full_logo_url: string,
        background_color: string,
        primary_color: string,
        checkout_mode: boolean,
        textCheckoutColor: string,
        textDetailsColor: string,
        checkout_logo: string
    },
    openpay_keys: {
        merchant_id: string,
        public_key: string
    },
    fintoc_keys: {
        public_key: string
    },
    vault_id: string,
    vault_url: string,
    reference: number,
    is_installments_available: boolean
}

Device Session ID

Using the getOpenpayDeviceSessionID method, you can retrieve your device session id. This method requires you to add the following parameters recovered with the getBusiness method:

openpay_keys.merchant_id: The Merchant ID associated with your store.
openpay_keys.public_key: Your Public Key.

You can recover your openpay_keys data from your merchantData returned from the Get Business method.

With the required parameters in hand, call the method as presented below:

  const { openpay_keys } = merchantData;

  const deviceSessionIdTonder = await liteCheckout.getOpenpayDeviceSessionID(
    openpay_keys.merchant_id,
    openpay_keys.public_key
  );

The returned data in deviceSessionIdTonder will be your device session id.

Customer

The customerRegister method allows you to create a new customer or retrieve an existing customer’s authorization token by adding their email address as the only parameter. Use the following code as example:

  const customerEmail = "john.c.calhoun@examplepetstore.com";

  const customerData = await liteCheckout.customerRegister(customerEmail);

Order

To create a new order with the Lite SDK, use the createOrder method. This method requires an object as parameter with the following data:

Field	Description
`business`	Your business’s API key.
`client`	Authentication token for the client recovered with the `customerRegister` method.
`billing_address_id`	ID of the billing address (null if not available).
`shipping_address_id`	ID of the shipping address (null if not available).
`amount`	Total amount of the order.
`status`	Status of the order.
`reference`	Reference information for the order. Recovered with the `getBusiness` method.
`is_oneclick`	Boolean indicating one-click order (true/false).
`items`	List of items in the shopping cart.

With the required parameter in hand, call the method as presented below:

  const cartItems = [
    {
      description: "Test product description",
      quantity: 1,
      price_unit: 25,
      discount: 0,
      taxes: 12,
      product_reference: 65421,
      name: "Test product",
      amount_total: 25
    }
  ]

  const { reference } = merchantData;

  const orderData = {
    business: apiKeyTonder,
    client: customerData.auth_token,
    billing_address_id: null,
    shipping_address_id: null,
    amount: total,
    status: A,
    reference: reference,
    is_oneclick: true,
    items: cartItems,
  };

  const jsonResponseOrder = await liteCheckout.createOrder(
    orderData
  );

The response to this method will be the following:

  {
    id: number,
    created: string,
    amount: string,
    status: string,
    payment_method?: string,
    reference?: string,
    is_oneclick: boolean,
    items: [
      {
        description: string,
        product_reference: string,
        quantity: string,
        price_unit: string,
        discount: string,
        taxes: string,
        amount_total: string
      }
    ],
    billing_address?: string,
    shipping_address?: string,
    client: {
      email: string,
      name: string,
      first_name: string,
      last_name: string,
      client_profile: {
        gender: string,
        date_birth?: string,
        terms: boolean,
        phone: string
      }
    }
  }

Payment

To create a new payment with the Lite SDK, use the createPayment method. This method requires an object as parameter with the following data:

Field	Description
business_pk	Primary key of the business for payment found in the `getBusiness` return object.
amount	Total amount for the payment.
date	Date of the payment (formatted as a string).
order	ID of the associated order in the JSON response, returned from the `createOrder` method.

With the required parameter in hand, call the method as presented below:

  const now = new Date();
  const dateString = now.toISOString();

  const paymentData = {
    business_pk: business.pk,
    amount: total,
    date: dateString,
    order: jsonResponseOrder.id,
  };

  const jsonResponsePayment = await liteCheckout.createPayment(
    paymentData
  );

The response to this method will be the following:

  {
    pk: number,
    order?: string,
    amount: string,
    status: string,
    date: string,
    paid_date?: string,
    shipping_address: {
      street: string,
      number: string,
      suburb: string,
      city: {
        name: string
      },
      state: {
        name: string,
        country: {
            name: string
        }
      },
      zip_code: string
    },
    shipping_address_id?: string,
    billing_address: {
      street: string,
      number: string,
      suburb: string,
      city: {
        name: string
      },
      state: {
        name: string,
        country: {
          name: string
        }
      },
      zip_code: string
    },
    billing_address_id?: string,
    client?: string,
    customer_order_reference?: string
  }

Tokenization

To retrieve the tokenized values you need to call the getSkyflowTokens method.

This method requires an object as parameter with vault_id and vault_url recovered with the getBusiness method, and a data object with the following information:

Field	Description
card_number	Card number entered in the payment form.
cvv	CVV (Card Verification Value) from the payment form.
expiration_month	Expiration month of the card from the payment form.
expiration_year	Expiration year of the card from the payment form.
cardholder_name	Cardholder’s name from the payment form.

These values above come from your html form.

With the required parameter in hand, call the method as presented below:

  const skyflowFields = {
    card_number: this.paymentForm.value.cardNumber,
    cvv: this.paymentForm.value.cvv,
    expiration_month: this.paymentForm.value.month,
    expiration_year: this.paymentForm.value.expirationYear,
    cardholder_name: this.paymentForm.value.name
  }

  const { vault_id, vault_url } = merchantData;


  const skyflowTokens = await liteCheckout.getSkyflowTokens({
    vault_id: vault_id,
    vault_url: vault_url,
    data: skyflowFields
  })

The response to this method will be the following:

  {
    vaultID: string,
    responses: [
      {
        records: [
            {
                skyflow_id: string
            }
        ]
      },
      {
          fields: {
              card_number: string,
              cardholder_name: string,
              cvv: string,
              expiration_month: string,
              expiration_year: string,
              skyflow_id: string
          }
      }
    ]
  }

Checkout Router

To retrieve the checkout router data you need to call the startCheckoutRouter method with an object as the only parameter. This object requires the following data:

Field	Description
card	Skyflow tokens representing the card information.
name	Cardholder’s name from tokens.
last_name	Customer’ last name.
email_client	Customer’s email address.
phone_number	Customer’s phone number.
return_url	URL to return after the transaction is completed.
id_product	ID of the product.
quantity_product	Quantity of the product.
id_ship	ID of the shipping.
instance_id_ship	Instance ID of the shipping.
amount	Total amount for the transaction.
title_ship	Title of the shipping.
description	Description of the transaction.
device_session_id	Device session ID for tracking.
token_id	Token ID.
order_id	ID of the associated order from JSON response.
business_id	ID of the business for the transaction.
payment_id	ID of the payment from JSON response.
source	Source identifier.

With the required parameter in hand, call the method as presented below:

  const customerPhone = "+11111111";
  const returnUrl = "http://localhost:8100/payment/success";

  const routerData = {
    card: skyflowTokens,
    name: skyflowTokens.cardholder_name,
    last_name: "",
    email_client: customerEmail,
    phone_number: customerPhone,
    return_url: returnUrl,
    id_product: "no_id",
    quantity_product: 1,
    id_ship: "0",
    instance_id_ship: "0",
    amount: total,
    title_ship: "shipping",
    description: "Transaction from the lite SDK",
    device_session_id: deviceSessionIdTonder,
    token_id: "",
    order_id: jsonResponseOrder.id,
    business_id: merchantData.business.pk,
    payment_id: jsonResponsePayment.pk,
    source: 'ionic-lite-sdk',
  };

  const jsonResponseRouter = await liteCheckout.startCheckoutRouter(
    routerData
  );

You need to take actions based on the checkout router response.

The response to this method will be the following:

  {
    status: 200,
    message: Success,
    psp_response: {
      id: string,
      authorization: number,
      operation_type: string,
      transaction_type: string,
      status: string,
      conciliated: boolean,
      creation_date: string,
      operation_date: string,
      description: string,
      error_message?: string,
      order_id?: string,
      card: {
        type: string,
        brand: string,
        address?: string,
        card_number: string,
        holder_name: string,
        expiration_year: string,
        expiration_month: string,
        allows_charges: boolean,
        allows_payouts: boolean,
        bank_name: string,
        points_type: string,
        points_card: boolean,
        bank_code: number
      },
      customer_id: string,
      gateway_card_present: string,
      amount: number,
      fee: {
        amount: number,
        tax: number,
        currency: string
      },
      payment_method: {
        type: string,
        url: string
      },
      currency: string,
      method: string,
      object: string
    },
    transaction_status: string,
    transaction_id: number,
    payment_id: number,
    provider: string,
    next_action: {
      redirect_to_url: {
        url: string,
        return_url: string,
        verify_transaction_status_url: string
      }
    },
    actions: [
      {
        name: string,
        url: string,
        method: string
      }
    ]
  }

3DS Verification

You can use the verify3dsTransaction() method to validate if a 3DS challenge was successful or not. Use the example below to call the method and handle the response as needed:

  inlineCheckout.verify3dsTransaction().then(response => {
    console.log('Verify 3ds response', response);
    
    if (response.transaction_status === 'Success') {
      alert('3DS Transaction verified.');
      // Proceed with normal payment flow
    } else if (response.transaction_status === 'Failed') {
      alert('3DS Transaction Failed');
    }
  });

Integrations

SDKs

Plugins

Ionic SDK Lite

Installation

Requirements

Configuration

Class Methods

Get Business

Device Session ID

Customer

Order

Payment

Tokenization

Checkout Router

3DS Verification

Get Business

Device Session ID

Customer

Order

Payment

Tokenization

Checkout Router

3DS Verification

Integrations

SDKs

Plugins

​Installation

​Requirements

​Configuration

​Class Methods

Get Business

Device Session ID

Customer

Order

Payment

Tokenization

Checkout Router

3DS Verification

​Get Business

​Device Session ID

​Customer

​Order

​Payment

​Tokenization

​Checkout Router

​3DS Verification

Installation

Requirements

Configuration

Class Methods

Get Business

Device Session ID

Customer

Order

Payment

Tokenization

Checkout Router

3DS Verification