@hubcommerce/sanalpos

Turkiye bankalarinin sanal POS (NestPay/EST) entegrasyonu icin TypeScript paketi.

Kaynak: vignetim/nestpay-api (MIT) uzerinden turetilmistir.

Dokumantasyon

• Resmi dokumandan net cevaplar
• Merchant onboarding (P0 / credential)
• Banka dokuman envanteri
• Uyum SOP
• Banka profilleri
• QA checklist
• Adapter contract
• Migration
• Changelog

Kurulum

npm install @hubcommerce/sanalpos

Yerel monorepo:

npm install file:../commerce-packages/payment/sanalpos

Hizli baslangic

import {
  SanalPosService,
  Currency,
  getSanalPosCredentials,
} from "@hubcommerce/sanalpos";

const service = new SanalPosService(getSanalPosCredentials());

// PCI-safe: kart bilgisi sunucuya gelmez — formFields istemcide doldurulur
const session = await service.initiate3DSecure({
  orderId: "SIP-123",
  amount: 199.9,
  currency: Currency.TRY,
  successUrl: "https://site.com/api/sanalpos/callback?result=ok",
  failureUrl: "https://site.com/api/sanalpos/callback?result=fail",
});

// session.formHtml veya session.formFields + session.redirectUrl

Akis

Magaza sunucusu → hash + rnd uretir
Tarayici → kart bilgisini dogrudan banka 3D gate'e POST eder
Banka → okUrl'e POST (HASH + mdStatus)
Magaza → verifyCallbackHash + mdStatus → siparis paid

Ortam degiskenleri

| Degisken | Aciklama | |----------|----------| | SANALPOS_CLIENT_ID | Magaza client ID | | SANALPOS_USERNAME | API kullanici adi | | SANALPOS_PASSWORD | API sifresi | | SANALPOS_STORE_KEY | 3D store key | | SANALPOS_BANK | isbank, akbank, ... | | SANALPOS_ENV | TEST veya PROD | | SANALPOS_STORETYPE | 3d, 3d_pay, 3d_pay_hosting | | SANALPOS_HASH_VERSION | ver3 (varsayilan) veya sha1 |

Ornek: .env.example

Void vs iade

| Islem | Ne zaman | Metod | |-------|----------|-------| | Void | Ayni gun | cancelWithOrderId() | | Credit | Ertesi gun / kismi | refund() |

Gelistirme

npm run build
npm test
npx tsx scripts/smoke-test.ts

Surum

v0.2.0 — ver3 callback, mdStatus, banka profilleri, test suite, PCI-safe form.