i-payment (JavaScript / TypeScript)

TypeScript-first client for the Kaspi integration API. Works in Node.js 18+ and any runtime with the native fetch API.

Installation

npm install i-payment

Quick start

import { KaspiClient } from "i-payment";

const client = new KaspiClient({ apiKey: "your-api-key" });

// List cashiers
const cashiers = await client.listCashiers();

// Create an invoice payment
const invoice = await client.createInvoice({
  phone: "77001234567",
  amount: 5000,
  comment: "Order #42",
});
console.log(invoice.Data?.OperationId);
console.log(invoice.Data?.Status); // "RemotePaymentCreated"

// Generate a QR code
const qr = await client.createQr({ amount: 1500 });
console.log(qr.Data?.QrToken);          // base64 QR image
console.log(qr.Data?.QrOperationId);    // poll this

// Poll QR status
const status = await client.qrStatus(qr.Data!.QrOperationId!);
console.log(status.Data?.Status); // "WaitingForPayment" | "Paid" | "Expired"

// Refund
await client.createRefund({ qr_operation_id: 12345678, return_amount: 1500 });

Methods

| Method | Description | |--------|-------------| | listCashiers() | Cashiers for the project | | clientInfo(phone, cashierId?) | Kaspi customer lookup | | createInvoice(params) | Invoice to customer's Kaspi app | | invoiceDetails(operationId, cashierId?) | Invoice status | | cancelInvoice(operationId, params?) | Cancel pending invoice | | invoiceHistory(params?) | Recent invoice history | | createQr(params) | QR code payment | | qrStatus(qrOperationId, cashierId?) | QR payment status | | operationsHistory(params) | Transaction history | | operationDetails(params) | Single operation details | | createRefund(params) | Refund a QR payment |

Error handling

import { ValidationError, AuthenticationError } from "i-payment";

try {
  await client.createInvoice({ phone: "bad", amount: -1 });
} catch (e) {
  if (e instanceof ValidationError) console.error(e.statusCode, e.message);
  else if (e instanceof AuthenticationError) console.error("Check your API key");
}

Options

const client = new KaspiClient({
  apiKey: "your-api-key",
  baseUrl: "https://api.ipay.kz", // default
  timeoutMs: 30_000,              // default
});