Infrastruktura e Sigurt e Pagesave Digjitale në Kosovë: Integrimi i NestPay (BKT, TEB, NLB), Stripe dhe 3D Secure 2.2 me Next.js 16

Tregu i tregtisë elektronike dhe shërbimeve dixhitale në Kosovë dhe Ballkanin Perëndimor po përjeton një transformim të thellë. Për vite me radhë, pagesat me para në dorë pas pranimit të porosisë (Cash on Delivery) mbulonin mbi 80% të vëllimit tregtar. Megjithatë, rritja e platformave SaaS, agjencive turistike online (OTA), klinikave private dhe shërbimeve B2B kërkon arkitekturë të sigurt për pranimin e pagesave me kartela bankare (Visa, Mastercard) në kohë reale.

Për inxhinierët softuerikë dhe drejtuesit e bizneseve, integrimi i pagesave online në Kosovë paraqet sfida specifike arkitekturore: koordinimi midis portaleve vendore të pagesave (si NestPay / Asseco SEE i përdorur nga BKT Kosova, TEB, dhe NLB Banka) dhe platformave ndërkombëtare si Stripe ose MoR (Merchant of Record) për diasporën dhe klientët globalë.

Në këtë artikull, Ekipi i Postieri XYZ L.L.C. shpalos arkitekturën e plotë të një motori pagesash modern, duke përfshirë fluksin 3D Secure 2.2, menaxhimin e çelësave të idempotencës (Idempotency Keys), dhe rrugëzimin e sigurt me Next.js 16 dhe PostgreSQL.

1. Topologjia e Pagesave: NestPay Vendor vs. Stripe Global

Në një arkitekturë moderne për tregun e Kosovës, zgjidhja optimale është një Smart Payment Gateway Switch që rrugëzon transaksionet sipas monedhës dhe kartelës së klientit:

┌─────────────────────────────────────────────────────────────┐
│                 Smart Payment Architecture                  │
└─────────────────────────────────────────────────────────────┘
                               │
               ┌───────────────▼───────────────┐
               │    Klienti (Next.js 16 UI)    │
               └───────────────┬───────────────┘
                               │ (Server Action / HTTPS)
               ┌───────────────▼───────────────┐
               │  Postieri Payment Gateway     │
               │   (Next.js App Router API)    │
               └───────────────┬───────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
    ┌──────────────────────┐        ┌──────────────────────┐
    │  NestPay / Asseco    │        │    Stripe Global     │
    │  (BKT, TEB, NLB)     │        │  (Diaspora, USD/CHF) │
    │  Kosovë & Shqipëri   │        │   Apple & Google Pay │
    └──────────┬───────────┘        └──────────┬───────────┘
               │                               │
               ▼                               ▼
    ┌──────────────────────────────────────────────────────┐
    │     3D Secure 2.2 MPI & ACS (Banka Emetuese)         │
    └──────────────────────────┬───────────────────────────┘
                               │ (Signed Callback / Webhook)
               ┌───────────────▼───────────────┐
               │  PostgreSQL Cluster w/ ACID   │
               │  Reconciliation & Order Audit │
               └───────────────────────────────┘

Kur duhet të përdoret NestPay dhe kur Stripe?

NestPay (BKT Kosova / TEB / NLB):
- Transaksione vendore në monedhën Euro (€).
- Norma provizioni të ulëta (interchange rate bankar vendor).
- Mbështetje për kartela debiti vendore pa bllokime nga rregulloret bankare vendore.
Stripe / Ndërkombëtare:
- Klientë nga diaspora (Zvicër, Gjermani, ShBA, Mbretëri e Bashkuar).
- Pagesa me një klikim nëpërmjet Apple Pay, Google Pay, dhe Link.
- Abonime periodike të përsëritura (Recurring SaaS Subscriptions).

2. Fluksi i Sigurisë 3D Secure 2.2 (SCA) në NestPay

NestPay përdor protokollin 3D Secure (3DS) ku blerësi autentikohet drejtpërdrejt te serveri i bankës së tij emetuese (ACS - Access Control Server). Për të parandaluar manipulimin e të dhënave, çdo kërkesë duhet të përmbajë një nënshkrim kriptografik HASH të gjeneruar me algoritmin SHA-512.

Formula e Gjenerimit të Nënshkrimit Kriptografik (SHA-512)

Parametrat kryesorë duhet të renditen saktësisht sipas specifikimit të NestPay:

typescript
// lib/payments/nestpay.ts
import crypto from "crypto";

interface NestPayParams {
  clientId: string;
  amount: string;      // Format: "10.00"
  oid: string;         // Unik Order ID
  okUrl: string;       // URL e suksesit (Callback)
  failUrl: string;     // URL e dështimit (Callback)
  rnd: string;         // Random salt
  storeKey: string;    // Çelësi sekret i dyqanit nga banka
  currency?: string;   // 978 për EUR
}

export function generateNestPaySignature(params: NestPayParams): string {
  const { clientId, oid, amount, okUrl, failUrl, rnd, storeKey } = params;
  
  // Renditja strikte e protokollit NestPay v3
  // clientid + oid + amount + okUrl + failUrl + trantype + rnd + storekey
  const tranType = "Auth"; // Autorizim i menjëhershëm
  const plainText = `${clientId}${oid}${amount}${okUrl}${failUrl}${tranType}${rnd}${storeKey}`;
  
  return crypto.createHash("sha512").update(plainText, "utf-8").digest("base64");
}

3. Implementimi i Krijimit të Pagesës me Next.js 16 Server Actions

Me Next.js 16 Server Actions, nuk kemi nevojë të ekspozojmë çelësat sekretë të bankës në anën e shfletuesit. Çdo transaksion inicohet në mënyrë të sigurt në server:

typescript
// app/actions/create-nestpay-checkout.ts
"use server";

import { generateNestPaySignature } from "@/lib/payments/nestpay";
import { getDbPool } from "@/lib/db";
import { v4 as uuidv4 } from "uuid";

export async function createNestPaySession(orderId: string, amount: number) {
  const pool = getDbPool();
  const rnd = uuidv4().substring(0, 12);
  const formattedAmount = amount.toFixed(2);
  const clientId = process.env.NESTPAY_CLIENT_ID!;
  const storeKey = process.env.NESTPAY_STORE_KEY!;
  const callbackBase = process.env.NEXT_PUBLIC_APP_URL!;

  const okUrl = `${callbackBase}/api/payments/nestpay/callback?status=success`;
  const failUrl = `${callbackBase}/api/payments/nestpay/callback?status=fail`;

  // 1. Regjistrimi i transaksionit me status 'pending' në PostgreSQL
  await pool.query(
    `INSERT INTO transactions (order_id, amount, currency, provider, status, idempotency_key, created_at)
     VALUES ($1, $2, 'EUR', 'nestpay', 'pending', $3, NOW())
     ON CONFLICT (order_id) DO UPDATE SET amount = EXCLUDED.amount, updated_at = NOW()`,
    [orderId, formattedAmount, rnd]
  );

  // 2. Gjenerimi i Hash-it të sigurt
  const hash = generateNestPaySignature({
    clientId,
    amount: formattedAmount,
    oid: orderId,
    okUrl,
    failUrl,
    rnd,
    storeKey,
  });

  return {
    gatewayUrl: process.env.NESTPAY_GATEWAY_URL!, // p.sh. https://epg.teb-kos.com/fim/est3Dgate
    formData: {
      clientid: clientId,
      amount: formattedAmount,
      oid: orderId,
      okUrl,
      failUrl,
      trantype: "Auth",
      currency: "978", // Kodi ISO për EUR
      rnd,
      hash,
      storetype: "3d_pay_hosting",
      lang: "sq",
    },
  };
}

4. Trajtimi i Callback-ut dhe Mbrojtja me Idempotencë në PostgreSQL

Kur përdoruesi përfundon verifikimin SMS OTP ose aplikacionin bankar, NestPay dërgon një kërkesë POST në rrugën tonë të kthimit (Callback).

Këtu duhet të kryhen tri veprime thelbësore:

Verifikimi i Nënshkrimit të Kthimit: Sigurimi që të dhënat nuk janë ndryshuar në rrugëtim.
Kontrolli i Statusit 3DS (mdStatus): mdStatus = 1 nënkupton autentikim të suksesshëm 3DS.
Idempotenca në Baza të Dhënave: Përdorimi i një transaksioni të izoluar SQL me kyçje (SELECT ... FOR UPDATE) për të parandaluar ekzekutimin e dyfishtë të porosive.

typescript
// app/api/payments/nestpay/callback/route.ts
import { NextResponse } from "next/server";
import { getDbPool } from "@/lib/db";
import crypto from "crypto";

export async function POST(req: Request) {
  try {
    const formData = await req.formData();
    const oid = formData.get("oid") as string;
    const response = formData.get("Response") as string;
    const mdStatus = formData.get("mdStatus") as string; // 1 = 3DS Success
    const authCode = formData.get("AuthCode") as string;
    const procReturnCode = formData.get("ProcReturnCode") as string;
    const incomingHash = formData.get("HASH") as string;
    const rnd = formData.get("rnd") as string;

    const pool = getDbPool();
    const client = await pool.connect();

    try {
      await client.query("BEGIN");

      // 1. Kyçja e transaksionit për të shmangur garën e konkurencës (Race Conditions)
      const txRes = await client.query(
        `SELECT id, status, amount FROM transactions WHERE order_id = $1 FOR UPDATE`,
        [oid]
      );

      if (txRes.rows.length === 0) {
        await client.query("ROLLBACK");
        return NextResponse.redirect(`${process.env.NEXT_PUBLIC_APP_URL}/checkout/error?reason=not_found`, 303);
      }

      const tx = txRes.rows[0];

      // Nëse transaksioni tashmë është procesuar, kthehu pa ri-ekzekutuar
      if (tx.status === "completed") {
        await client.query("COMMIT");
        return NextResponse.redirect(`${process.env.NEXT_PUBLIC_APP_URL}/checkout/success?orderId=${oid}`, 303);
      }

      // 2. Verifikimi i suksesit nga Banka
      const isApproved = response === "Approved" && procReturnCode === "00" && (mdStatus === "1" || mdStatus === "2");

      if (isApproved) {
        // Përditëso transaksionin dhe porosinë
        await client.query(
          `UPDATE transactions 
           SET status = 'completed', auth_code = $1, raw_response = $2, updated_at = NOW() 
           WHERE id = $3`,
          [authCode, JSON.stringify(Object.fromEntries(formData)), tx.id]
        );

        await client.query(
          `UPDATE orders SET payment_status = 'paid', updated_at = NOW() WHERE id = $1`,
          [oid]
        );

        await client.query("COMMIT");
        return NextResponse.redirect(`${process.env.NEXT_PUBLIC_APP_URL}/checkout/success?orderId=${oid}`, 303);
      } else {
        await client.query(
          `UPDATE transactions SET status = 'failed', updated_at = NOW() WHERE id = $1`,
          [tx.id]
        );
        await client.query("COMMIT");
        return NextResponse.redirect(`${process.env.NEXT_PUBLIC_APP_URL}/checkout/error?reason=declined`, 303);
      }
    } catch (dbErr) {
      await client.query("ROLLBACK");
      throw dbErr;
    } finally {
      client.release();
    }
  } catch (error) {
    console.error("[NestPay Callback Error]:", error);
    return NextResponse.redirect(`${process.env.NEXT_PUBLIC_APP_URL}/checkout/error?reason=server_error`, 303);
  }
}

5. Integrimi me Stripe për Diasporën dhe Blerësit Globalë

Për klientët që përdorin Apple Pay, Google Pay ose kartela të huaja, integrimi i Stripe me Next.js 16 Server Actions ofron përvojën më të shpejtë të arkëtimit:

typescript
// app/actions/create-stripe-session.ts
"use server";

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-06-20",
});

export async function createStripeCheckoutSession(orderId: string, amountEur: number, customerEmail: string) {
  const session = await stripe.checkout.sessions.create({
    payment_method_types: ["card"],
    line_items: [
      {
        price_data: {
          currency: "eur",
          product_data: {
            name: `Shërbimi / Porosia #${orderId}`,
          },
          unit_amount: Math.round(amountEur * 100),
        },
        quantity: 1,
      },
    ],
    mode: "payment",
    customer_email: customerEmail,
    client_reference_id: orderId,
    success_url: `${process.env.NEXT_PUBLIC_SITE_URL}/checkout/success?session_id={CHECKOUT_SESSION_ID}&orderId=${orderId}`,
    cancel_url: `${process.env.NEXT_PUBLIC_SITE_URL}/checkout/canceled?orderId=${orderId}`,
  });

  return { url: session.url };
}

6. Standardi i Sigurisë PCI-DSS: Zvogëlimi i Riskut (Scope Reduction)

Një gabim i rëndë që haset shpesh në zhvillimin e platformave e-commerce në Kosovë është dërgimi i numrave të kartelave (PAN) apo kodeve CVV direkt në serverët e aplikacionit. Kjo e vendos të gjithë infrastrukturën nën kërkesat e rrepta të PCI-DSS Level 1, duke kërkuar auditime periodike të shtrenjta.

Zgjidhja Arkitekturore e Rekomanduar nga Postieri XYZ:

Zero-Storage Policy: Serverët e Postieri XYZ dhe aplikacionet e klientëve tanë nuk prekin dhe nuk ruajnë asnjëherë të dhëna kartelash.
Hosted Payment Pages & Iframes: Klienti ridrejtohet në formularët e sigurt të certifikuar të bankës ose Stripe Elements me iFrame të izoluar.
Mutual TLS & Webhook Signing: Çdo komunikim Server-to-Server kryhet ekskluzivisht përmes kanaleve të enkriptuara me nënshkrim HMAC.

7. Përmbledhje dhe Përfitimet për Bizneset në Kosovë

Zbatimi i një arkitekture të qëndrueshme të pagesave digjitale ofron përparësi thelbësore:

Konvertim më i Lartë: Blerësit vendorë paguajnë shpejt me kartela të bankave vendore, ndërsa diaspora përdor Apple Pay / Google Pay.
Zero Pagesa të Dyfishta: Mbrojtja me ACID transactions dhe Idempotency Keys eliminon plotësisht gabimet e rrjetit.
Pajtueshmëri e Plotë Ligjore dhe Financiare: Sinkronizimi i menjëhershëm me sistemet e faturimit dhe librat kontabël në Kosovë.

Në Postieri XYZ L.L.C., ne ndërtojmë dhe mirëmbajmë infrastrukturë softuerike të shkallës së lartë për e-commerce, sisteme rezervimesh (OTA), dhe platforma SaaS. Nëse dëshironi të integroni pagesa automatike dhe të sigurta në biznesin tuaj, kontaktoni ekipin tonë inxhinierik.