@tonder.io/ionic-lite-sdk

Tonder SDK

Tonder SDK helps to integrate the services Tonder offers in your own mobile app

Table of Contents

1. Installation
2. Usage
3. Configuration Options
4. Mobile Settings
5. Payment Data Structure
6. Field Validation Functions
7. API Reference
8. Examples
9. Deprecated Fields
10. Deprecated Functions
11. License

Installation

You can install using NPM

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

Add dependencies to the root of the app (index.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>

Usage

LiteCheckout allows you to build a custom checkout interface using Tonder's core functionality

Import LiteCheckout class

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

Create instance

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

// The configureCheckout function allows you to set initial information,
// such as the customer's email, which is used to retrieve a list of saved cards, save new card, etc.
inlineCheckout.configureCheckout({ customer: { email: "[e-mail]" } });

// Initialize the checkout
await liteCheckout.injectCheckout();

// To verify a 3ds transaction you can use the following method
// It should be called after the injectCheckout method
// The response status will be one of the following
// ['Declined', 'Cancelled', 'Failed', 'Success', 'Pending', 'Authorized']

inlineCheckout.verify3dsTransaction().then(response => {
    console.log('Verify 3ds response', response)
})

// Retrieve customer's saved cards
const cards = await liteCheckout.getCustomerCards();

// Save a new card
const newCard = await liteCheckout.saveCustomerCard(cardData);

// Remove a saved card
await liteCheckout.removeCustomerCard(cardId);

// Get available payment methods
const paymentMethods = await liteCheckout.getCustomerPaymentMethods();

// Process a payment
const paymentResponse = await liteCheckout.payment(paymentData);

Configuration Options

Property	Type	Description
mode	string	Environment mode. Options: 'stage', 'production', 'sandbox', 'development'. Default: 'stage'
apiKey	string	Your API key from the Tonder Dashboard
returnrl	string	URL where the checkout form is mounted (used for 3DS)
callBack	function	Callback function to be invoked after the payment process ends successfully.

Mobile settings

If you are deploying to Android, edit your AndroidManifest.xml file to add the Internet permission.

<!-- Required to fetch data from the internet. -->
<uses-permission android:name="android.permission.INTERNET" />

Likewise, if you are deploying to macOS, edit your macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements files to include the network client entitlement.

<!-- Required to fetch data from the internet. -->
<key>com.apple.security.network.client</key>
<true>

Payment Data Structure

When calling the payment method, use the following data structure:

Field Descriptions

• customer: Object containing the customer's personal information to be registered in the transaction.

• cart: Object containing the total amount and an array of items to be registered in the Tonder order.

  • total: The total amount of the transaction.
  • items: An array of objects, each representing a product or service in the order.
    • name: name of the product
    • price_unit: valid float string with the price of the product
    • quantity: valid integer string with the quantity of this product

• currency: String representing the currency code for the transaction (e.g., "MXN" for Mexican Peso).

• metadata: Object for including any additional information about the transaction. This can be used for internal references or tracking.

• card: (for LiteCheckout) Object containing card information. This is used differently depending on whether it's a new card or a saved card:

  • For a new card: Include card_number, cvv, expiration_month, expiration_year, and cardholder_name.
  • For a saved card: Include only the skyflow_id of the saved card.
  • This is only used when not paying with a payment_method.

• payment_method: (for LiteCheckout) String indicating the alternative payment method to be used (e.g., "Spei"). This is only used when not paying with a card.

• apm_config: (Optional) Configuration object for APM-specific options. Only applicable when using alternative payment methods like Mercado Pago.

APM Config Fields - Mercado Pago

Field	Type	Description
binary_mode	boolean	If true, payment must be approved or rejected immediately (no pending).
additional_info	string	Extra info shown during checkout and in payment details.
back_urls	object	URLs to redirect the user after payment.
└─ success	string	Redirect URL after successful payment.
└─ pending	string	Redirect URL after pending payment.
└─ failure	string	Redirect URL after failed/canceled payment.
auto_return	"approved" | "all"	Enables auto redirection after payment completion.
payment_methods	object	Payment method restrictions and preferences.
└─ excluded_payment_methods[]	array	List of payment methods to exclude.
└─ excluded_payment_methods[].id	string	ID of payment method to exclude (e.g., "visa").
└─ excluded_payment_types[]	array	List of payment types to exclude.
└─ excluded_payment_types[].id	string	ID of payment type to exclude (e.g., "ticket").
└─ default_payment_method_id	string	Default payment method (e.g., "master").
└─ installments	number	Max number of installments allowed.
└─ default_installments	number	Default number of installments suggested.
expires	boolean	Whether the preference has expiration.
expiration_date_from	string (ISO 8601)	Start of validity period (e.g. "2025-01-01T12:00:00-05:00").
expiration_date_to	string (ISO 8601)	End of validity period.
differential_pricing	object	Configuration for differential pricing.
└─ id	number	ID of the differential pricing strategy.
marketplace	string	Marketplace identifier (default: "NONE").
marketplace_fee	number	Fee to collect as marketplace commission.
tracks[]	array	Ad tracking configurations.
└─ type	"google_ad" | "facebook_ad"	Type of tracker.
└─ values.conversion_id	string	Google Ads conversion ID.
└─ values.conversion_label	string	Google Ads label.
└─ values.pixel_id	string	Facebook Pixel ID.
statement_descriptor	string	Text on payer’s card statement (max 16 characters).
shipments	object	Shipping configuration.
└─ mode	"custom" | "me2" | "not_specified"	Type of shipping mode.
└─ local_pickup	boolean	Enable pickup at local branch (for me2).
└─ dimensions	string	Package dimensions (e.g. 10x10x10,500).
└─ default_shipping_method	number	Default shipping method (for me2).
└─ free_methods[]	array	Shipping methods offered for free (for me2).
└─ free_methods[].id	number	ID of free shipping method.
└─ cost	number	Shipping cost (only for custom mode).
└─ free_shipping	boolean	If true, shipping is free (custom only).
└─ receiver_address	object	Shipping address.
└─ receiver_address.zip_code	string	ZIP or postal code.
└─ receiver_address.street_name	string	Street name.
└─ receiver_address.street_number	number	Street number.
└─ receiver_address.city_name	string	City name.
└─ receiver_address.state_name	string	State name.
└─ receiver_address.country_name	string	Country name.
└─ receiver_address.floor	string	Floor (optional).
└─ receiver_address.apartment	string	Apartment or unit (optional).

const paymentData = {
  customer: {
    firstName: "John",
    lastName: "Doe",
    country: "USA",
    address: "123 Main St",
    city: "Anytown",
    state: "CA",
    postCode: "12345",
    email: "[e-mail]",
    phone: "1234567890",
    identification:{
        type: "CPF",
        number: "19119119100"
    }
  },
  cart: {
    total: "100.00",
    items: [
      {
        description: "Product description",
        quantity: 1,
        price_unit: "100.00",
        discount: "0.00",
        taxes: "0.00",
        product_reference: "PROD123",
        name: "Product Name",
        amount_total: "100.00",
      },
    ],
  },
  currency: "MXN",
  metadata: {
    order_id: "ORDER123",
  },
  // For a new card:
  card: {
    card_number: "4111111111111111",
    cvv: "123",
    expiration_month: "12",
    expiration_year: "25",
    cardholder_name: "John Doe",
  },
  // card: "skyflow_id" // for a selected saved card.
  // payment_method: "Spei", // For the selected payment method.
  // apm_config: {} // Optional, only for APMs like Mercado Pago, Oxxo Pay
};

Field Validation Functions

For LiteCheckout implementations, the SDK provides validation functions to ensure the integrity of card data before submitting:

• validateCardNumber(cardNumber): Validates the card number using the Luhn algorithm.
• validateCardholderName(name): Checks if the cardholder name is valid.
• validateCVV(cvv): Ensures the CVV is in the correct format.
• validateExpirationDate(expirationDate): Validates the expiration date in MM/YY format.
• validateExpirationMonth(month): Checks if the expiration month is valid.
• validateExpirationYear(year): Validates the expiration year.

Example usage:

import {
  validateCardNumber,
  validateCardholderName,
  validateCVV,
  validateExpirationDate,
} from "@tonder.io/ionic-lite-sdk";

const cardNumber = "4111111111111111";
const cardholderName = "John Doe";
const cvv = "123";
const expirationDate = "12/25";

if (
  validateCardNumber(cardNumber) &&
  validateCardholderName(cardholderName) &&
  validateCVV(cvv) &&
  validateExpirationDate(expirationDate)
) {
  // Proceed with payment
} else {
  // Show error message
}

API Reference

LiteCheckout Methods

• configureCheckout(data): Set initial checkout data
• injectCheckout(): Initialize the checkout
• getCustomerCards(): Retrieve saved cards
• saveCustomerCard(cardData): Save a new card
• removeCustomerCard(cardId): Remove a saved card
• getCustomerPaymentMethods(): Get available payment methods
• payment(data): Process a payment
• verify3dsTransaction(): Verify a 3DS transaction

Important Note about SaveCard functionality: To properly implement the SaveCard feature, you must use a SecureToken. For detailed implementation instructions and best practices, please refer to our official documentation on How to use SecureToken for secure card saving.

Examples

Here are examples of how to implement Tonder Lite SDK:

Angular

For Angular, we recommend using a service to manage the Tonder instance:

// tonder.service.ts
import { Injectable } from "@angular/core";
import { LiteCheckout } from "@tonder.io/ionic-lite-sdk";
import {ILiteCheckout} from "@tonder.io/ionic-lite-sdk/dist/types/liteInlineCheckout";

@Injectable({
  providedIn: "root",
})
export class TonderService {
  private liteCheckout!: ILiteCheckout;

  constructor(@Inject(Object) private sdkParameters: IInlineLiteCheckoutOptions) {
    this.initializeInlineCheckout();
  }

  private initializeInlineCheckout(): void {
    this.liteCheckout = new LiteCheckout({ ...this.sdkParameters });
  }

  configureCheckout(customerData: IConfigureCheckout): void {
    return this.liteCheckout.configureCheckout({ ...customerData });
  }

  async injectCheckout(): Promise<void> {
    return await this.liteCheckout.injectCheckout();
  }

  verify3dsTransaction(): Promise<ITransaction | IStartCheckoutResponse | void> {
    return this.liteCheckout.verify3dsTransaction();
  }

  payment(
      checkoutData: IProcessPaymentRequest,
  ): Promise<IStartCheckoutResponse> {
      return this.inlineCheckout.payment(checkoutData);
  }

  // Add more functions, for example for lite sdk: get payment methods

  // getCustomerPaymentMethods(): Promise<IPaymentMethod[]> {
  //     return this.liteCheckout.getCustomerPaymentMethods();
  // }
}

// checkout.component.ts
import { Component, OnInit, OnDestroy } from "@angular/core";
import { TonderService } from "./tonder.service";

@Component({
  selector: "app-tonder-checkout",
  template: `
    <div id="container">
      <form [formGroup]="paymentForm">
        <div class="lite-container-tonder">
            <div id="id-name" class="empty-div">
              <label for="name">Namess: </label>
              <input id="name" type="text" formControlName="name">
            </div>
            <div id="id-cardNumber" class="empty-div">
              <label for="cardNumber">Card number: </label>
              <input id="cardNumber" type="text" formControlName="cardNumber">
            </div>
            <div class="collect-row">
              <div class="empty-div">
                <label for="month">Month: </label>
                <input id="month" type="text" formControlName="month">
              </div>
              <div class="expiration-year">
                <label for="expirationYear">Year: </label>
                <input id="expirationYear" type="text" formControlName="expirationYear">
              </div>
              <div class="empty-div">
                <label for="cvv">CVV: </label>
                <input id="cvv" type="text" formControlName="cvv">
              </div>
            </div>
          <div id="msgError">{{ errorMessage }}</div>
          <div id="msgNotification"></div>
          <div class="container-pay-button">
            <button class="lite-pay-button" (click)="onPayment($event)">Pay</button>
          </div>
        </div>
    
      </form>
    </div>
  `,
  providers: [
    {
      provide: TonderInlineService,
      // Initialization of the Tonder Lite SDK.
      // Note: Replace these credentials with your own in development/production.
      useFactory: () =>
        new TonderInlineService({
          apiKey: "11e3d3c3e95e0eaabbcae61ebad34ee5f93c3d27",
          returnUrl: "http://localhost:8100/tabs/tab5",
          mode: "stage",
        }),
    },
  ],
})
export class TonderCheckoutComponent implements OnInit, OnDestroy {
  loading = false;
  checkoutData: IProcessPaymentRequest;
  paymentForm = new FormGroup({
      name: new FormControl('Pedro Paramo'),
      cardNumber: new FormControl('4242424242424242'),
      month: new FormControl('12'),
      expirationYear: new FormControl('28'),
      cvv: new FormControl('123')
  });
  
  constructor(private tonderService: TonderService) {
      this.checkoutData = {
          customer: {
              firstName: "Jhon",
              lastName: "Doe",
              email: "[e-mail]",
              phone: "[phone]"
          },
          cart: {
              total: 25,
              items: [
                  {
                      description: "Test product description",
                      quantity: 1,
                      price_unit: 25,
                      discount: 1,
                      taxes: 12,
                      product_reference: 89456123,
                      name: "Test product",
                      amount_total: 25
                  }
              ]
          },
          metadata: {},
          currency: "MXN"
      }
  }

  ngOnInit() {
    this.initCheckout();
  }

  async initCheckout() {
    this.tonderService.configureCheckout({
      customer: { email: "[e-mail]" },
    });
    await this.tonderService.injectCheckout();
    this.tonderService.verify3dsTransaction().then((response) => {
      console.log("Verify 3ds response", response);
    });
    
    // Calls more functions to get payment methods, saved cards, etc.
  }

  async pay() {
    this.loading = true;
    try {
      const response = await this.tonderService.payment({
          ...this.checkoutData,
          card: { // Card details, if not using a payment method.
              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 || ""
          },
          // card: "skyflow_id" // In case a saved card is selected.
          // payment_method: "" // Payment method if not using the card form
      });
      console.log("Payment successful:", response);
      alert("Payment successful");
    } catch (error) {
      console.error("Payment failed:", error);
      alert("Payment failed");
    } finally {
      this.loading = false;
    }
  }
}

Request secure token

const jsonResponse = await liteCheckout.getSecureToken(
  secretApiKey //You can take this from you Tonder Dashboard 
);

Return secure token

{
    access: string;
}

Deprecated Fields

The following fields have been deprecated and should no longer be used. Consider using the recommended alternatives:

Register customer card

apiKeyTonder Property

• Deprecated Reason: The apiKeyTonder property in the constructor and IInlineLiteCheckoutOptions interface is no longer required.
• Alternative: Use the apiKey field.

baseUrlTonder Property

• Deprecated Reason: The baseUrlTonder property in the constructor and IInlineLiteCheckoutOptions interface is no longer required.
• Alternative: Use the mode field with stage | development | sandbox | production options.

signal Property

• Deprecated Reason: The signal property in the constructor and IInlineLiteCheckoutOptions interface is no longer required.

Deprecated Functions

The following functions have been deprecated and should no longer be used. Consider using the recommended alternatives:

customerRegister

• Deprecated Reason: This function is no longer necessary as registration is now automatically handled during payment processing or when using card management methods.

createOrder and createPayment

• Deprecated Reason: These functions have been replaced by the payment function, which now automatically handles order creation and payment processing.
• Alternative: Use the payment function.

startCheckoutRouter and startCheckoutRouterFull

• Deprecated Reason: These functions have been replaced by the payment function.
• Alternative: Use the payment function.

registerCustomerCard

• Deprecated Reason: This function has been renamed to saveCustomerCard to better align with its purpose. The method's usage has also been updated.
• Alternative: Use the saveCustomerCard method and update your implementation to reflect the changes.

deleteCustomerCard

• Deprecated Reason: This function has been renamed to removeCustomerCard to better align with its purpose. The method's usage has also been updated.
• Alternative: Use the removeCustomerCard method and update your implementation to reflect the changes.

getActiveAPMs

• Deprecated Reason: This function has been renamed to getCustomerPaymentMethods to better align with its purpose. The method's usage has also been updated.
• Alternative: Use the getCustomerPaymentMethods method and update your implementation to reflect the changes.

getSkyflowTokens

• Deprecated Reason: Card registration and checkout are now automatically handled during the payment process or through card management methods, making this method unnecessary.

getOpenpayDeviceSessionID

• Deprecated Reason: It is no longer necessary to use this method is now automatically handled during the payment process.

Notes

General

• Replace apiKey, mode, returnUrl with your actual values.
• Remember to use the configureCheckout function after creating an instance of LiteCheckout. This ensures that functions such as payment processing, saving cards, deleting cards, and others work correctly.

Script Dependencies

For all implementations, ensure you include the necessary scripts:

<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>

License

MIT