Tingg Checkout SDK

Introduction | Installation | License

Introduction

Integrate your JavaScript app with Tingg checkout in minutes using our feature rich & flexible SDK.

• Validation
• Encryption
• Typescript types
• Pre-built react, vue & angular modules (coming soon)

Installation

The SDK can be installed via NPM using the command below:

npm i @tingg-sdk/checkout

Usage

Express checkout integration

@tingg-sdk/checkout exposes a function create that initiates a checkout call and returns back the redirect link a customer can use to redirect to express checkout .

Ensure you get your OAuth keys to continue. See docs

1. Import / require the checkout module

import { create } from "@tingg-sdk/checkout";

2. See below implementation. Where the response is destructured into variable error and data

• apiKey is required and is a non-empty string
• clientId is required and is a non-empty string
• clientSecret is required and is a non-empty string
• payload is required and is a non-empty object
• environment parameter is optional. Defaults to sandbox

For async/await

const {error, data} = await create({apiKey, clientId, clientSecret, payload }, 'testing')

if (error === null) {
    // Handle redeirect link here
    console.log(data.long_url)
    console.log(data.short_url)
}

// else Handle errors if error key is not null

For .then()

create({apiKey, clientId, clientSecret, payload}, 'testing').then(({error, data}) => {
    if (error === null) {
        // Handle redeirect link here
        console.log(data.long_url)
        console.log(data.short_url)
    }
    
    // else Handle errors if error key is not null
    
})

Express checkout integration (deprecated)

@tingg-sdk/checkout exposes a function checkout creates a checkout request by validating and encrypting the payload

Ensure you get your Encryption keys to continue. See docs

1. Import / require the checkout module

import { checkout } from "@tingg-sdk/checkout";

2. Implementations

• payload is required and is a non-empty object
• ivKey is required and should be a 16 character string
• secretKey is required and should be a 16 character string
• accessKey is required and is a non-empty string
• environment parameter is optional. Defaults to sandbox

For async/await

const { error, data } = await checkout({ payload, ivKey, secretKey, accessKey });

if (error === null) {
    res.status(200).json({
        access_key: accessKey,
        redirectURL: data.url,
        encrypted_payload: data.encrypted_payload,
    });
}

Example

Let's look at a simple Express app

import express from "express";
import { checkout, create } from "@tingg-sdk/checkout";
import "dotenv/config";

const port = process.env.PORT || 3000;
const app = express();


// Use json middleware to parse JSON in the request body
app.use(express.json());


//  A sample for value for req.body
// {
// merchant_transaction_id: "mtr-dg9823euy3a",
// account_number: "acc-14n345j5599",
// msisdn: "254700000000",
// service_code: "JOHNDOEONLINE",
// country_code: "KEN",
// currency_code: "KES",
// customer_last_name: "John",
// customer_first_name: "Doe",
// customer_email: "[email protected]",
// request_amount: "100",
// due_date: "2023-11-18 16:15:30",
// language_code: "en",
// request_description: "Dummy merchant transaction",
// fail_redirect_url: "https://webhook.site/88390df9-a496-432f-abe5-0cf3380fda54",
// success_redirect_url: "https://webhook.site/88390df9-a496-432f-abe5-0cf3380fda54",
// callback_url: "https://webhook.site/88390df9-a496-432f-abe5-0cf3380fda54",
// };

/**
 * Initiates a checkout call and returns back the redirect link a customer can use to redirect to express checkout .
 */

app.post("/create", async (req, res) => {
    // Get these values from your .env config
    const apiKey = process.env.API_KEY;
    const clientId = process.env.CLIENT_ID;
    const clientSecret = process.env.CLIENT_SECRET;

    // Get the JSON payload from the request
    const payload = req.body;

    const { error, data } = await create({apiKey, clientId, clientSecret, payload }, "testing");

    if (error == null) {
        //data: {long_url: string, short_url: string}
        res.status(200).send(data);
        return;
    }
    // Handle errors if error key is not null
    // Include validation errors and authentication errors
    res.status(400).send({
        status: 400,
        error: error,
    });
});

/**
 * Creates a checkout request by validating and encrypting the payload
 * @deprecated Use {@link create} instead
 */
app.post("/checkout", async (req, res) => {
    // Get these values from your .env config
    const ivKey = process.env.IV_KEY;
    const accessKey = process.env.ACCESS_KEY;
    const secretKey = process.env.SECRET_KEY;

    // Get the JSON payload from the request
    const payload = req.body;

    const { error, data } = await checkout({ payload, ivKey, secretKey, accessKey });

    // Handle errors if error key is not null
    // 1. Contains validation errors if any i.e {"<payload_field>": "validation error message"}
    // 2. Contains encryption errors if any i.e {"ivKey|secretKey|message": "encryption error message"}

    if (error === null) {
        res.status(200).json({
            access_key: accessKey,
            redirectURL: data.url,
            encrypted_payload: data.encrypted_payload,
        });
        return
    }
    res.status(400).send({
        status: 400,
        error: error,
    });
});

app.listen(port, () => {
    console.log(`[Example app]: Server is running at http://localhost:${port}`);
});

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE.txt for more information.