Tonder’s JS SDK Lite Checkout gives you freedom to build your own checkout interface while taking advantage of our core functionalities. This guide will take you step-by-step into integrating it.

If you haven’t installed and pre-configured Tonder’s JS SDK, refer to the Installation guide here.

​
Configuration

Before initializing an instance of Tonder SDK, ensure that you have configured it properly. Follow the usage example below:

1

Add the required ID to your HTML

Tonder’s JS SDK needs an entry point to operate. This entry point is defined by adding a tonder-checkout ID to an empty div, like the example below:

<div>
    <h1>Checkout</h1>
    <!-- You have to add an entry point with the ID 'tonder-checkout' -->
    <div id="tonder-checkout">
    </div>
</div>
2

Initialize Tonder's SDK Instance

Initialize Tonder’s JS SDK instance with the following parameters:

FieldDescription
modeEnvironment mode. Options: stage, production, sandbox. Default: stage
apiKeyThe API key used for authentication and authorization.
returnUrlThe URL to which the user is redirected after the checkout process, regardless of success or failure.
customizationThis object is designed to customize the behavior of the checkout. It is used to adjust both the interface options and operational parameters. Refer to the Customizations section for more details.
stylesCustom styles object that allows you to customize the appearance of the inline checkout. It may include properties such as colors, fonts, and other styling options. Refer to the Styling section for more details.
3

Configure checkout method (Optional)

You can use the configureCheckout method to set initial customer information, such as their email address, allowing to retrieve the respectives user’s saved cards.

liteCheckout.configureCheckout({ customer: { email: "example@email.com" } });
4

Inject checkout method

Call the injectCheckout method with your inlineCheckout instance, with the code below:

liteCheckout.injectCheckout();

With this, you can render the checkout to your customers.

5

Add a pay button

Lastly, you need to create a button to submit the form. This button needs to have an event listener that calls the payment method from the liteCheckout instance, sending the checkout data as payload, like presented below:

document.getElementById('your-pay-button').addEventListener('click', async () => {
  try {
    response = await liteCheckout.payment(checkoutData);
    if (response.transaction_status === 'Success') {
      alert('Payment successful.');
    } else if (response.transaction_status === 'Pending') {
      alert('Payment pending. Redirecting to 3DS...');
      // The redirection to 3DS occurs automatically
    } else {
      alert('Payment declined.');
    }
  } catch (error) {
    alert('Error with payment.');
  }
});

After Completing these steps, you can use the Lite Checkout available methods to manage your user’s experience.

​
Class Methods

With your Lite Checkout instance configured, you’ll have at your disposal the following methods:

Cards

Get Customer Payment Methods

Payment

3DS Verification

​
Cards

Tonder’s SDK offers the following methods to manage customer cards:

  • getCustomerCards
  • saveCustomerCard
  • removeCustomerCard
You need to use the secureToken to be able to manage cards with Tonder’s SDK. Refer to the How to Use secureToken for Secure Card Saving to learn how to do this.

​
Get Customer Cards

Use the getCustomerCards method to retrieve previously saved customer cards:

const cards = await liteCheckout.getCustomerCards();

​
Save Customer Card

Use the saveCustomerCard method to save a new card into the system. This method requires an object as parameter to define the card’s properties:

Sure! Here’s a markdown table with the keys and their descriptions:

KeyDescription
card_numberThe credit card number without spaces or dashes.
cvvThe card verification value, a 3 or 4-digit code.
expiration_monthThe month when the card expires.
expiration_yearThe year when the card expires.
cardholder_nameThe full name of the cardholder as on the card.
const cards = await liteCheckout.saveCustomerCard({
    card_number: "4111111111111111",
    cvv: "123",
    expiration_month: "12",
    expiration_year: "25",
    cardholder_name: "John Doe",
  });

​
Remove Customer Card

Use the removeCustomerCards method to delete a previously saved customer card by passing the card ID as parameter:

const cards = await liteCheckout.removeCustomerCards(cardId);

​
Get Customer Payment Methods

Use this method to retrieve the customer previously registered payment methods:

const paymentMethods = await liteCheckout.getCustomerPaymentMethods();

​
Payment

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

KeyDescription
customerAn object containing customer information
cartAn object containing cart and item details
currencyThe currency code for the transaction (e.g., “MXN”)
metadataAn object for additional metadata (e.g., order ID)
cardAn object containing card details for a new card
payment_methodThe selected payment method (optional)
  const paymentData = {
    customer: {
      firstName: "John",
      lastName: "Doe",
      country: "USA",
      address: "123 Main St",
      city: "Anytown",
      state: "CA",
      postCode: "12345",
      email: "john.doe@example.com",
      phone: "1234567890",
    },
    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.
  };

  const responsePayment = await liteCheckout.payment(paymentData);

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

const verificationResult = await liteCheckout.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');
    }
  });

​
Field Validation

Tonder’s SDK provides validation functions to ensure the integrity of card data before submitting them:

FunctionDescription
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
import {
  validateCardNumber,
  validateCardholderName,
  validateCVV,
  validateExpirationDate,
} from "tonder-web-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
}

​
Full Integration Example

For full integration example codes, refer to the Code Examples page.

StylingCode Examples