KisPay Telegram Bot Universal Integration Guide for Merchants

1. Introduction

This section provides a universal guide for integrating the KisPay Payment Gateway into Telegram bots, regardless of the programming language used. Whether you develop your bot in Python, Node.js, or another language, this guide outlines the key components, logic flow, and integration steps required to process payments using KisPay.

2. Integration Goal

Enable merchants to:

• Accept payments directly from Telegram users.
• Generate a KisPay checkout session dynamically.
• Monitor and confirm payments in real time.

3. Common Architecture

Regardless of programming language, every Telegram bot payment integration with KisPay follows the same architecture:

1. Telegram Bot API – Handles user interactions (messages, commands, buttons).

2. Backend Server – Communicates with KisPay API to create and check payment sessions.

3. KisPay API – Manages checkout sessions, payment pages, and status updates.

4. Webhook/Long Polling – Connects the bot to Telegram updates.

4. KisPay API Endpoints

Base URL: https://api.kispay.et 

5. Required Parameters

When creating a checkout session, the following fields must be included in your request body:

6. Integration Steps (Language-Independent)

Step 1: User Interaction

Your bot should:

1. Greet the user (/start command).
2. Display payment options such as Pay Now.
3. Ask the user for amount and phone number.

Step 2: Create Payment Session

Send a POST request to:

https://api.kispay.et/api/checkout/create_checkout_session

with your KisPay API key in headers:

{
  "Content-Type": "application/json",
  "x-api-key": "<YOUR_KISPAY_API_KEY>"
}

Step 3: Handle the Response

The response includes a paymentUrl. Send this link back to the user with a Telegram message or inline button:

✓ Payment session created!

Click below to complete your payment:

[ Pay Now ]

Step 4: Poll or Webhook Payment Status

Check payment completion using:

GET https://api.kispay.et/api/checkout/hooks/status/{sessionId}

You can poll every few seconds or set up a webhook listener to update payment status.

Step 5: Confirm to the User

Depending on the status, send the user a message:

• Payment completed successfully!
• Payment failed. Please try again.
• Payment time expired.

7. Implementation Examples

Node.js (Telegraf + Express)

const { Telegraf } = require("telegraf");
const fetch = require("node-fetch");
const bot = new Telegraf("<TELEGRAM_BOT_TOKEN>");
const API_KEY = "<KISPAY_API_KEY>";
 
bot.start((ctx) => ctx.reply("Welcome to KisPay Payment Bot! Choose Pay to continue."));
 
bot.hears("Pay", async (ctx) => {
  const res = await fetch("https://api.kispay.et/api/checkout/create_checkout_session", {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
    body: JSON.stringify({ amount: 50, orderNo: "Order-" + Date.now(), fullName: "User", email: "user@demo.com", phone: "0912345678" }),
  });
  const data = await res.json();
  ctx.reply(" Pay here: " + data.body.paymentUrl);
});
 
bot.launch();

Python (python-telegram-bot + Flask)

from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import ApplicationBuilder, CommandHandler, MessageHandler, filters, ContextTypes
import requests, json
 
API_KEY = '<KISPAY_API_KEY>'
TOKEN = '<TELEGRAM_BOT_TOKEN>'
 
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(' Welcome! Type /pay to start payment.')
 
async def pay(update: Update, context: ContextTypes.DEFAULT_TYPE):
    payload = {
        "amount": 100,
        "orderNo": f"Order-{update.effective_user.id}",
        "fullName": update.effective_user.full_name,
        "email": "bot@user.com",
        "phone": "0912345678",
        "redirectUrl": "https://merchant-domain/success"
    }
    headers = {'Content-Type': 'application/json', 'x-api-key': API_KEY}
    res = requests.post('https://api.kispay.et/api/checkout/create_checkout_session', headers=headers, data=json.dumps(payload))
    data = res.json()
    btn = InlineKeyboardMarkup([[InlineKeyboardButton('💵 Pay Now', url=data['body']['paymentUrl'])]])
    await update.message.reply_text('Proceed to payment below:', reply_markup=btn)
 
app = ApplicationBuilder().token(TOKEN).build()
app.add_handler(CommandHandler('start', start))
app.add_handler(CommandHandler('pay', pay))
app.run_polling()

Other Languages (General Logic)

For any language (Java, PHP, Go, etc.), the logic remains the same:

1. Collect payment details.
2. Make a POST request to create a checkout session.
3. Retrieve and share the paymentUrl.
4. Poll or listen for payment status.
5. Notify the user based on result.

8. Security Best Practices

• Store API keys and tokens in environment variables.
• Always use HTTPS endpoints.
• Validate user input (phone, amount, etc.) before creating sessions.

9. Testing Checklist

10. Support

For technical support or sandbox API keys, contact: 📧 support@kispay.et

✓ Summary

This guide provides a universal template for integrating KisPay payments in Telegram bots across all major programming languages. Merchants can adapt it easily to Python, Node.js, PHP, Java, or any preferred technology stack.