@uveysservetoglu/kobil-payment

KOBIL Pay (mpay-merchant) client for Node.js / TypeScript, with automatic OAuth token management and typed models.

npm install @uveysservetoglu/kobil-payment

Quick start

OAuth credentials (tokenEndpoint, clientId, clientSecret) are shared across KOBIL modules and read from KOBIL_* env vars if you don't pass them. merchantId defaults to clientId.

import { PaymentClient, paymentGroup } from "@uveysservetoglu/kobil-payment";

const payment = new PaymentClient({
  // credentials (or via KOBIL_TOKEN_ENDPOINT / KOBIL_CLIENT_ID / KOBIL_CLIENT_SECRET):
  tokenEndpoint: process.env.KOBIL_TOKEN_ENDPOINT!,
  clientId: process.env.KOBIL_CLIENT_ID!,
  clientSecret: process.env.KOBIL_CLIENT_SECRET!,
  // payment-specific:
  paymentBaseUrl: "https://pay.cloud.kobil.com/mpay-merchant/create/transaction",
  merchantName: "ISPARK",
  defaultCurrency: "TRY",
  defaultMerchantCallback: "https://yourapi.com/payment-callback",
});

Amounts are in the smallest currency unit (1300 = 13.00 TRY). Timeouts in minutes.

The six operations

// 1. Regular payment (immediate charge)
const res = await payment.createTransaction({
  userId,
  amount: 1300,
  paymentContent: paymentGroup(["Service Amount", "10.0 TL"], ["Tax Amount", "3.0 TL"]),
});
// res.transactionId ; parsePaymentStatus(res) === "new"

// 2. Pre-authorization (hold funds)
const pre = await payment.createPreAuthTransaction({ userId, amount: 1300 });
// pre.nextAction holds the post-auth handle

// 3. Post-authorization (settle final amount)
await payment.postAuth({ transactionId: pre.transactionId!, amount: 40 });

// 4. Status
const status = await payment.getStatus({ transactionId });

// 5. Cancel (void)
await payment.cancel({ transactionId, userId, cancellationMessage: "Iptal" });

// 6. Refund (partial or full)
await payment.refund({ transactionId, userId, amount: 5555, currency: "USD" });

JavaScript usage is identical (const { PaymentClient } = require("@uveysservetoglu/kobil-payment")).

Errors

All operations throw KobilPaymentError (extends KobilError) with statusCode and responseBody when available.

import { KobilPaymentError } from "@uveysservetoglu/kobil-payment";
try {
  await payment.createTransaction({ userId, amount: 1300 });
} catch (e) {
  if (e instanceof KobilPaymentError) console.error(e.statusCode, e.responseBody);
}

License

MIT