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:

1

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.

2

Initialize Tonder's SDK Instance

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

FieldDescription
signalSignal from AbortController instance if it needs cancel the request.
baseUrlTonderTonder’s API base URL.
-> Live server: https://stage.tonder.io
-> Mock Server: https://stoplight.io/mocks/tonder/tonder-api-v1-2/3152148
apiKeyTonderYour 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 
  });
3

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:

ParameterTypeDescription
orderobjectRepresents the details of each item in the order.
totalnumberThe total amount for the order. This should match the sum of the costs of items in the order.
customerobjectInformation about the customer.
skyflowTokensobjectThe details of the card to be used on the transaction.
return_urlstringURL to which the customer will be redirected after the checkout process is completed.
isSandboxbooleanA boolean indicating if the transaction is being processed in a sandbox environment for testing purposes.
metadataobjectOptional additional data about the order that might be used for processing or tracking.
currencystringThe 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;
  };
4

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:

FieldTypeDescription
statusnumberThe HTTP status code reflecting the outcome of the checkout process.
messagestringA message providing additional information about the response.
psp_responseobjectAn object containing detailed information from the payment service provider.
transaction_statusstringStatus of the transaction as reported by the system.
transaction_idnumberA unique identifier for the transaction.
payment_idnumberA unique identifier for the payment linked to the transaction.
providerstringThe payment service provider(PSP) that is handling the transaction.
next_actionobjectURLs to redirect the user for each possible situation.
actionsArray<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

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();

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:

FieldDescription
businessYour business’s API key.
clientAuthentication token for the client recovered with the customerRegister method.
billing_address_idID of the billing address (null if not available).
shipping_address_idID of the shipping address (null if not available).
amountTotal amount of the order.
statusStatus of the order.
referenceReference information for the order. Recovered with the getBusiness method.
is_oneclickBoolean indicating one-click order (true/false).
itemsList 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
  );

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:

FieldDescription
business_pkPrimary key of the business for payment found in the getBusiness return object.
amountTotal amount for the payment.
dateDate of the payment (formatted as a string).
orderID 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
  );

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:

FieldDescription
card_numberCard number entered in the payment form.
cvvCVV (Card Verification Value) from the payment form.
expiration_monthExpiration month of the card from the payment form.
expiration_yearExpiration year of the card from the payment form.
cardholder_nameCardholder’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
  })

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:

FieldDescription
cardSkyflow tokens representing the card information.
nameCardholder’s name from tokens.
last_nameCustomer’ last name.
email_clientCustomer’s email address.
phone_numberCustomer’s phone number.
return_urlURL to return after the transaction is completed.
id_productID of the product.
quantity_productQuantity of the product.
id_shipID of the shipping.
instance_id_shipInstance ID of the shipping.
amountTotal amount for the transaction.
title_shipTitle of the shipping.
descriptionDescription of the transaction.
device_session_idDevice session ID for tracking.
token_idToken ID.
order_idID of the associated order from JSON response.
business_idID of the business for the transaction.
payment_idID of the payment from JSON response.
sourceSource 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.

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.status === 'Success') {
      alert('3DS Transaction verified.');
      // Proceed with normal payment flow
    } else if (response.status === 'Failed') {
      alert('3DS Transaction Failed');
    }
  });