@rekl0w/sanal-pos

evrenonur/sanalpos yaklaşımını Node.js, Bun ve TypeScript dünyasına taşıyan, testli ve npm paketlemeye hazır bir sanal POS orkestrasyon katmanı.

Bu repo iki şekilde kullanılabilir:

Kütüphane olarak: SanalPosClient üzerinden satış, 3D dönüş, iptal, iade ve sorgu akışları
HTTP API olarak: Hono üstünden JSON endpoint'leri ile servisleşmiş kullanım

Not: Bu sürüm, referans projedeki gerçek banka / provider akışlarını TypeScript tarafına async olarak taşır. Node.js ve Bun ile kullanılabilir; dokümante edilmemiş katalog kayıtları için fallback davranış korunur, dokümante edilen gateway aileleri gerçek HTTP/XML/JSON transport ile çalışır.

Özellikler

Hono + Node.js/Bun + TypeScript mimarisi
Referans listedeki 48 banka / ödeme kuruluşu kataloğu
Tek istemci sınıfı: async SanalPosClient
3D'siz satış ve 3D satış başlangıç akışları
3D callback / dönüş işleme akışı
İptal ve iade işlemleri
BIN ve taksit sorguları
Banka listesi filtreleme
Gerçek gateway contract testleri + opsiyonel canlı smoke testleri
Zod tabanlı request doğrulama
Vitest ile kapsamlı test seti
Güvenlik taraması yapılmış bağımlılıklar

Gereksinimler

Node.js >= 18.18.0 veya Bun >= 1.3.0
TypeScript >= 6
XML/JSON tabanlı banka gateway'leri için ağ erişimi
Canlı smoke test için .env.example dosyasından türetilmiş bir .env ve gerçek merchant bilgileri

Kurulum

Kütüphane olarak kurmak için:

npm install @rekl0w/sanal-pos

Alternatifleri:

pnpm add @rekl0w/sanal-pos
yarn add @rekl0w/sanal-pos
bun add @rekl0w/sanal-pos

Repo geliştirme kurulumu için:

npm install

Kullanılabilir sanal POS'lar

Sanal POS	Satış	Satış 3D	İptal	İade	Durum
Akbank	✔️	✔️	✔️	✔️	Gerçek gateway
Akbank Nestpay	✔️	✔️	✔️	✔️	Gerçek gateway
Albaraka Türk	✔️	✔️	✔️	✔️	Fallback / katalog
Alternatif Bank	✔️	✔️	✔️	✔️	Gerçek gateway
Anadolubank	✔️	✔️	✔️	✔️	Gerçek gateway
Denizbank	✔️	✔️	✔️	✔️	Gerçek gateway
Fibabanka	✔️	✔️	✔️	✔️	Fallback / katalog
QNB Finansbank	✔️	✔️	✔️	✔️	Gerçek gateway
Finansbank Nestpay	✔️	✔️	✔️	✔️	Gerçek gateway
Garanti BBVA	✔️	✔️	❌	❌	Gerçek gateway
Halkbank	✔️	✔️	✔️	✔️	Gerçek gateway
HSBC	✔️	✔️	✔️	✔️	Fallback / katalog
ING Bank	✔️	✔️	✔️	✔️	Gerçek gateway
İş Bankası	✔️	✔️	✔️	✔️	Gerçek gateway
Odeabank	✔️	✔️	✔️	✔️	Fallback / katalog
Türk Ekonomi Bankası	✔️	✔️	✔️	✔️	Gerçek gateway
Türkiye Finans	✔️	✔️	✔️	✔️	Gerçek gateway
Vakıfbank	✔️	✔️	✔️	✔️	Gerçek gateway
Yapı Kredi Bankası	✔️	✔️	❌	❌	Gerçek gateway
Şekerbank	✔️	✔️	✔️	✔️	Gerçek gateway
Ziraat Bankası	✔️	✔️	✔️	✔️	Gerçek gateway
Aktif Yatırım Bankası	✔️	✔️	✔️	✔️	Fallback / katalog
Kuveyt Türk	✔️	✔️	❌	❌	Gerçek gateway
Vakıf Katılım	✔️	✔️	❌	❌	Gerçek gateway
Ziraat Katılım	✔️	✔️	✔️	✔️	Fallback / katalog
Paynet	✔️	✔️	✔️	✔️	Gerçek gateway
PayNKolay	✔️	✔️	✔️	✔️	Gerçek gateway
HalkÖde	✔️	✔️	✔️	✔️	Gerçek gateway
Tami	✔️	✔️	✔️	✔️	Gerçek gateway
VakıfPayS	✔️	✔️	✔️	✔️	Gerçek gateway
ZiraatPay	✔️	✔️	✔️	✔️	Gerçek gateway
Vepara	✔️	✔️	✔️	✔️	Gerçek gateway
Moka	✔️	✔️	✔️	✔️	Gerçek gateway
Ahlpay	✔️	✔️	✔️	✔️	Gerçek gateway
IQmoney	✔️	✔️	✔️	✔️	Gerçek gateway
Parolapara	✔️	✔️	✔️	✔️	Gerçek gateway
PayBull	✔️	✔️	✔️	✔️	Gerçek gateway
ParamPos	✔️	✔️	✔️	✔️	Gerçek gateway
QNBpay	✔️	✔️	✔️	✔️	Gerçek gateway
Sipay	✔️	✔️	✔️	✔️	Gerçek gateway
Hepsipay	✔️	✔️	✔️	✔️	Fallback / katalog
Payten (MSU)	✔️	✔️	✔️	✔️	Gerçek gateway
PayTR	✔️	✔️	✔️	✔️	Fallback / katalog
IPara	✔️	✔️	✔️	✔️	Fallback / katalog
PayU	✔️	✔️	✔️	✔️	Fallback / katalog
Iyzico	✔️	✔️	✔️	✔️	Gerçek gateway
Cardplus	✔️	✔️	✔️	✔️	Gerçek gateway
Paratika	✔️	✔️	✔️	✔️	Gerçek gateway

Fallback / katalog etiketi, bu repodaki katalog kaydının documented: false olmasına ve BankService.createGateway() çağrısında gerçek gateway yerine SandboxGateway çözülmesine dayanır. Yani bu kayıtlar katalogda vardır; ancak bu pakette şu an gerçek binding yerine kontrollü fallback davranışı ile çalışır.

Çalıştırma

Geliştirme:

npm run dev

Normal çalıştırma:

npm run start

Varsayılan port: 3000

Aynı scriptler hem npm run ... hem bun run ... ile çalışır. Örneğin npm run start yerine doğrudan bun run start da kullanabilirsiniz.

Test ve doğrulama

Testler:

npm test

Tip kontrolü:

npm run typecheck

Toplu kontrol:

npm run check

Paket build:

npm run build

Opsiyonel canlı smoke test:

# .env.example dosyasını .env olarak kopyalayıp merchant bilgilerini doldurduktan sonra
npm run test:live

Bağımlılık güvenlik taraması:

npm audit

API bilgileri - `MerchantAuth`

bank_code (string): Banka / ödeme kuruluşu kodu. BankCodes veya BankService sabitleri kullanılabilir.
merchant_id (string): Firma kodu / üye işyeri numarası / client code.
merchant_user (string): API kullanıcı adı / terminal no / app id.
merchant_password (string): API şifresi / terminal safe id / secret.
merchant_storekey (string): 3D store key / merchant key / guid / secret key.
test_platform (boolean): true test ortamı, false canlı ortam.
installment_commission_policy (InstallmentCommissionPolicy): CCPayment tabanlı kuruluşlarda taksit komisyon davranışını belirler.

CCPayment taksit komisyon politikası

InstallmentCommissionPolicy sabiti ile CCPayment ailesinde taksit komisyon davranışı kontrol edilebilir:

InstallmentCommissionPolicy.Default: gateway varsayılan davranışını kullanır
InstallmentCommissionPolicy.ChargeToCustomer: komisyon müşteriye yansıtılır
InstallmentCommissionPolicy.AbsorbByMerchant: komisyon satıcı üzerinde bırakılır

import {
  BankCodes,
  InstallmentCommissionPolicy,
  SanalPosClient,
} from "@rekl0w/sanal-pos";

await SanalPosClient.sale(request, {
  bank_code: BankCodes.QNBPAY,
  merchant_id: "merchant-id",
  merchant_user: "merchant-user",
  merchant_password: "merchant-password",
  merchant_storekey: "merchant-storekey",
  test_platform: true,
  installment_commission_policy: InstallmentCommissionPolicy.ChargeToCustomer,
});

Banka bazlı credential alan eşlemesi

Sanal POS	`bank_code`	`merchant_id`	`merchant_user`	`merchant_password`	`merchant_storekey`
Akbank	`BankCodes.AKBANK`	İş Yeri No	`merchantSafeId`	`terminalSafeId`	Secret Key
Nestpay ailesi	İlgili Nestpay kodu	Mağaza Kodu	API Kullanıcısı	API Şifresi	3D Storekey
Garanti BBVA	`BankCodes.GARANTI_BBVA`	Firma Kodu	Terminal No	PROVAUT Şifresi	3D Anahtarı
Vakıfbank	`BankCodes.VAKIFBANK`	Üye İşyeri No	POS No	API Şifresi	—
Yapı Kredi	`BankCodes.YAPI_KREDI`	Firma Kodu	Terminal No	PosNet ID	ENCKEY
CCPayment ailesi	İlgili CCPayment kodu	Üye İşyeri ID	Uygulama Anahtarı	Uygulama Parolası	Merchant Key
Paynet	`BankCodes.PAYNET`	Paynet Merchant ID	Basic Auth kullanıcı	Basic Auth şifresi	—
ParamPos	`BankCodes.PARAMPOS`	Client Code	Kullanıcı Adı	Şifre	Guid Anahtar
Moka	`BankCodes.MOKA`	Bayi Kodu	API Kullanıcısı	API Şifresi	—
Ahlpay	`BankCodes.AHLPAY`	Member ID	API Kullanıcısı	API Şifresi	API Key
Payten ailesi	İlgili Payten kodu	Firma Kodu	API Kullanıcısı	API Şifresi	Dealer Type / ek anahtar
Tami	`BankCodes.TAMI`	Üye İşyeri No	Terminal No	`KidValue / KValue` (pipe-separated)	Secret Key
PayNKolay	`BankCodes.PAYNKOLAY`	`sx` token / merchant id	`sx` list	`sx` iptal	Secret Key
Iyzico	`BankCodes.IYZICO`	Üye İşyeri No	API Anahtarı	Güvenlik Anahtarı	—

HTTP API

Sağlık kontrolü

GET /health

Banka listesi

GET /api/banks

İsteğe bağlı filtreler:

collective_vpos=true|false
installment_api=true|false
supports_refund=true|false

Tek banka detayı

GET /api/banks/:bankCode

Satış

POST /api/sale

Örnek payload:

{
  "auth": {
    "bank_code": "9990",
    "merchant_id": "20158",
    "merchant_user": "07fb70f9d8de575f32baa6518e38c5d6",
    "merchant_password": "61d97b2cac247069495be4b16f8604db",
    "merchant_storekey": "$2y$10$N9IJkgazXMUwCzpn7NJrZePy3v.dIFOQUyW4yGfT3eWry6m.KxanK",
    "test_platform": true
  },
  "request": {
    "order_number": "ORDER-001",
    "customer_ip_address": "1.1.1.1",
    "sale_info": {
      "card_name_surname": "test kart",
      "card_number": "4022780520669303",
      "card_expiry_month": 1,
      "card_expiry_year": 2050,
      "card_cvv": "988",
      "amount": 10,
      "currency": 949,
      "installment": 1
    },
    "payment_3d": {
      "confirm": false
    },
    "invoice_info": {
      "name": "cem",
      "surname": "pehlivan"
    },
    "shipping_info": {
      "name": "cem",
      "surname": "pehlivan"
    }
  }
}

3D dönüş işleme

POST /api/sale/3d-response

İptal

POST /api/cancel

İade

POST /api/refund

BIN sorgusu

POST /api/query/bin

Satış sorgusu

POST /api/query/sale

Taksit sorguları

POST /api/query/installments/all
POST /api/query/installments/additional

Kütüphane kullanımı

import { BankCodes, CurrencyMap, SanalPosClient } from "@rekl0w/sanal-pos";

const response = await SanalPosClient.sale(
  {
    order_number: "ORDER-001",
    customer_ip_address: "1.1.1.1",
    sale_info: {
      card_name_surname: "test kart",
      card_number: "4022780520669303",
      card_expiry_month: 1,
      card_expiry_year: 2050,
      card_cvv: "988",
      amount: 10,
      currency: CurrencyMap.TRY,
      installment: 1,
    },
    payment_3d: { confirm: false },
    invoice_info: { name: "cem", surname: "pehlivan" },
    shipping_info: { name: "cem", surname: "pehlivan" },
  },
  {
    bank_code: BankCodes.QNBPAY,
    merchant_id: "20158",
    merchant_user: "07fb70f9d8de575f32baa6518e38c5d6",
    merchant_password: "61d97b2cac247069495be4b16f8604db",
    merchant_storekey:
      "$2y$10$N9IJkgazXMUwCzpn7NJrZePy3v.dIFOQUyW4yGfT3eWry6m.KxanK",
    test_platform: true,
  },
);

console.log(response.status, response.transaction_id);

Desteklenen işlem yüzeyi

sale
sale3DResponse
cancel
refund
binInstallmentQuery
allInstallmentQuery
additionalInstallmentQuery
saleQuery
allBankList

Mimari

src/
├── app.ts                      # Hono uygulaması
├── client/
│   └── sanalpos-client.ts      # Tek giriş istemcisi
├── domain/
│   ├── banks.ts                # Banka / provider kataloğu
│   ├── enums.ts                # Enum sabitleri
│   ├── schemas.ts              # Zod şemaları
│   └── types.ts                # Domain tipleri
├── gateways/
│   ├── abstract-gateway.ts     # Ortak gateway soyutlaması
│   ├── bank-gateways.ts        # Gerçek banka gateway implementasyonları
│   ├── provider-gateways.ts    # Gerçek provider gateway implementasyonları
│   ├── sandbox-gateway.ts      # Deterministic sandbox davranışı
│   └── types.ts                # Gateway interface'i
├── infra/
│   ├── http-client.ts          # HTTP taşıma katmanı
│   ├── payment-utils.ts        # Hash/format yardımcıları
│   ├── xml.ts                  # XML parse/build yardımcıları
│   └── iyzico-pki.ts           # Iyzico PKI/JWT yardımcıları
├── config/
│   └── gateway-config.ts       # Endpoint ve familya konfigurasyonları
└── services/
    ├── bank-service.ts         # Banka servis katmanı
    ├── bin-service.ts          # BIN / taksit mantığı
    ├── sanitizer-service.ts    # Veri sanitizasyonu
    └── validation-service.ts   # İş kuralı validasyonları

Güvenlik notu

axios kullanılmadı
npm audit ve bun audit ile temiz doğrulama alınabilir
Kart ve müşteri alanları sanitize edilir
Doğrulama hataları kontrollü JSON response olarak döner

Hata yönetimi

Gerçek HTTP isteklerinde bağlantı, timeout veya upstream hata durumları HttpRequestError olarak yükseltilir. İş kuralı / input problemleri ise ValidationError üzerinden döner.

import {
  HttpRequestError,
  SanalPosClient,
  ValidationError,
} from "@rekl0w/sanal-pos";

try {
  const response = await SanalPosClient.sale(request, auth);
  console.log(response.status);
} catch (error) {
  if (error instanceof HttpRequestError) {
    console.error(error.url, error.statusCode, error.responseBody);
  }

  if (error instanceof ValidationError) {
    console.error(error.issues);
  }
}

Canlı entegrasyon notu

SanalPosClient metotları async çalışır
Dokümante edilen bankalar/providerlar BankService.createGateway içinde gerçek gateway sınıflarına bağlanır
Dokümante edilmemiş katalog kayıtları kontrollü fallback ile çalışmaya devam eder
Paketle birlikte .env.example gelir; bunu .env olarak kopyalayıp gerçek smoke testleri buradan yönetebilirsiniz

Referans

Bu proje, evrenonur/sanalpos repo akışlarını TypeScript/Bun tarafına taşır.
Referans PHP paketinin kendisi de cempehlivan/CP.VPOS mimarisi üzerine kuruludur.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
server.ts		server.ts
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

@rekl0w/sanal-pos

Özellikler

Gereksinimler

Kurulum

Kullanılabilir sanal POS'lar

Çalıştırma

Test ve doğrulama

API bilgileri - `MerchantAuth`

CCPayment taksit komisyon politikası

Banka bazlı credential alan eşlemesi

HTTP API

Sağlık kontrolü

Banka listesi

Tek banka detayı

Satış

3D dönüş işleme

İptal

İade

BIN sorgusu

Satış sorgusu

Taksit sorguları

Kütüphane kullanımı

Desteklenen işlem yüzeyi

Mimari

Güvenlik notu

Hata yönetimi

Canlı entegrasyon notu

Referans

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

@rekl0w/sanal-pos

Özellikler

Gereksinimler

Kurulum

Kullanılabilir sanal POS'lar

Çalıştırma

Test ve doğrulama

API bilgileri - MerchantAuth

CCPayment taksit komisyon politikası

Banka bazlı credential alan eşlemesi

HTTP API

Sağlık kontrolü

Banka listesi

Tek banka detayı

Satış

3D dönüş işleme

İptal

İade

BIN sorgusu

Satış sorgusu

Taksit sorguları

Kütüphane kullanımı

Desteklenen işlem yüzeyi

Mimari

Güvenlik notu

Hata yönetimi

Canlı entegrasyon notu

Referans

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

API bilgileri - `MerchantAuth`