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.
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;
};
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
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.
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
);
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
);
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. |
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:
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
);
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');
}
});