@finisai/medusa-payment-moka

Bu kütüphane bağımsız olarak geliştirilmiştir; Moka United'ın resmi ürünü değildir, Moka United tarafından geliştirilmemiş, onaylanmamış ve desteklenmemektedir.

Moka United sanal POS entegrasyonu için Medusa v2 ödeme sağlayıcısı (payment provider).

Bu paket, Moka United API üzerinden 3D Secure ödeme akışını Medusa'nın ödeme modülüne bağlar. Ödeme başlatma, 3D Secure hash doğrulaması (CodeForHash + T/F kuralı), ön provizyon ve capture, iptal (void) ve iade işlemlerini kapsar. Aynı ailenin diğer paketleri: moka-python (saf Python istemcisi) ve moka-django (Django uygulaması).

Özellikler

• 3D Secure ile ödeme (DoDirectPaymentThreeD): müşteri bankanın doğrulama sayfasına yönlendirilir
• Callback doğrulaması: hashValue, SHA-256(CodeForHash + "T"/"F") kuralıyla doğrulanır
• Ön provizyon desteği (isPreAuth ayarı ile IsPreAuth=1 + DoCapture)
• Ödeme iptali (DoVoid) ve iade talebi (DoCreateRefundRequest, kısmi iade dahil)
• Ödeme detayı sorgulama (GetDealerPaymentTrxDetailList)
• Havuz ödemesi onaylama / onay iptali ve taksit tablosu hesaplama (istemci üzerinden)
• Saklı kartla (CardToken) ödeme desteği
• CheckKey otomatik üretimi, TLS 1.2 zorunlu HTTP katmanı, hassas alan maskeli debug logları
• Test kartları yardımcısı ve kapsamlı jest test paketi

Gereksinimler

• Node.js 20 ve üzeri
• Medusa v2 (@medusajs/framework >= 2.0.0)

Kurulum

npm install @finisai/medusa-payment-moka

medusa-config.ts dosyanızda ödeme modülüne sağlayıcıyı ekleyin:

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@finisai/medusa-payment-moka",
            id: "moka",
            options: {
              dealerCode: process.env.MOKA_DEALER_CODE,
              username: process.env.MOKA_USERNAME,
              password: process.env.MOKA_PASSWORD,
              callbackUrl: process.env.MOKA_CALLBACK_URL,
              environment: "test", // canli ortam icin "production"
              software: "yazilim adiniz",
            },
          },
        ],
      },
    },
  ],
})

Sağlayıcıyı Medusa admin panelinden ilgili region'a ekleyin (ödeme sağlayıcısı kimliği: pp_moka_moka).

Ayarlar

| Ayar | Zorunlu | Varsayılan | Açıklama | | --- | --- | --- | --- | | dealerCode | Evet | - | Moka United bayi kodu | | username | Evet | - | API kullanıcı adı | | password | Evet | - | API şifresi | | callbackUrl | Evet | - | 3D doğrulama sonrası Moka United'ın sonucu POST edeceği vitrin adresi | | environment | Hayır | "production" | "test": service.refmokaunited.com, "production": service.mokaunited.com | | baseUrl | Hayır | - | Verilirse environment ayarını ezer (örneğin eski service.refmoka.com adresi için) | | software | Hayır | "medusa-payment-moka" | İsteklerde gönderilen yazılım adı | | isPreAuth | Hayır | false | true ise ödeme ön provizyon olarak başlar, capture anında çekilir | | debug | Hayır | false | İstek/yanıt logları (kart ve kimlik bilgileri maskelenir) |

CheckKey değeri (DealerCode + "MK" + Username + "PD" + Password bilgisinin SHA-256 özeti) her istekte otomatik üretilir.

Ödeme Akışı

Moka United, iyzico'dan farklı olarak 3D doğrulamasını gömülü HTML yerine yönlendirme URL'i ile yapar:

1. Vitrin, ödeme oturumunu kart bilgileriyle günceller ve ödemeyi başlatır. Sağlayıcı DoDirectPaymentThreeD çağırır; oturum verisine redirectUrl (banka doğrulama sayfası) ve codeForHash yazılır, durum requires_more olur.
2. Vitrin, müşteriyi session.data.redirectUrl adresine yönlendirir.
3. Müşteri kartı doğruladığında Moka United, callbackUrl adresinize şu form alanlarını POST eder: hashValue, resultCode, resultMessage, trxCode, OtherTrxCode.
4. Vitrindeki callback route'u bu alanları ödeme oturumunun verisine işler ve cart complete akışını çalıştırır.
5. authorizePayment, hashValue değerini oturumdaki codeForHash ile doğrular: SHA-256(CodeForHash + "T") eşleşirse ödeme yetkilendirilir ve trxCode (VirtualPosOrderId) saklanır; iptal ve iade işlemleri bu değerle yapılır.

Kart verisi alanları

Ödeme oturumu verisine (session.data) şu alanlar yazılarak ödeme başlatılır:

| Alan | Açıklama | | --- | --- | | card_holder_name | Kart sahibinin adı soyadı | | card_number | Kart numarası | | expire_month | Son kullanma ayı (MM) | | expire_year | Son kullanma yılı (YYYY) | | cvc | Güvenlik kodu | | card_token | Saklı kartla ödeme için token (kart alanları yerine) | | installment_number | Taksit sayısı (varsayılan 1) | | client_ip | Müşterinin IP adresi | | description | Ödeme açıklaması |

Callback route örneği (vitrin / storefront)

// Ornek: Next.js route handler
// Moka United bu adrese form POST atar; alanlar odeme oturumuna islenir
// ve cart complete cagrilir.
export async function POST(request: Request) {
  const form = await request.formData()
  const payload = {
    hashValue: form.get("hashValue") as string,
    resultCode: (form.get("resultCode") as string) ?? "",
    resultMessage: (form.get("resultMessage") as string) ?? "",
    trxCode: (form.get("trxCode") as string) ?? "",
    OtherTrxCode: form.get("OtherTrxCode") as string,
  }

  // 1. OtherTrxCode ile odeme oturumunu bulun (baslatirken sakladiniz)
  // 2. Oturum verisini payload ile guncelleyin (updatePaymentSession)
  // 3. Cart complete cagirin: authorizePayment hash dogrulamasini yapar
  // 4. Musteriyi siparis onay veya hata sayfasina yonlendirin
}

Hash doğrulamasını kendiniz yapmak isterseniz:

import { verifyThreeDsResult } from "@finisai/medusa-payment-moka"

const sonuc = verifyThreeDsResult(codeForHash, hashValue)
// true: basarili, false: basarisiz, null: gecersiz / kurcalanmis istek

İade ve İptal

Medusa admin üzerinden yapılan refund ve cancel işlemleri, oturumda saklanan virtualPosOrderId değeriyle Moka United'a iletilir:

• İptal: /PaymentDealer/DoVoid
• İade: /PaymentDealer/DoCreateRefundRequest (tutar verilerek kısmi iade yapılabilir)

Ön Provizyon (isPreAuth)

isPreAuth: true ayarı ile ödeme IsPreAuth=1 olarak başlar; Medusa'da capture tetiklendiğinde /PaymentDealer/DoCapture çağrılarak tutar çekilir. Ayar kapalıyken Moka ödemeyi doğrudan çeker ve capture no-op'tur.

Test Kartları

Test ortamında (environment: "test") Moka United test kartları kullanılabilir. Bu kartlarla yapılan ödemeler bankaya gönderilmez; cevap Moka United sisteminden döner. Güncel test kartı listesi için resmi dokümantasyona bakınız (liste zaman içinde değişebilir):

https://developer.mokaunited.com/home.php?page=test-kartlari

Geliştirme kolaylığı için kartlara kod içinden de erişilebilir:

import { TEST_CARDS, getTestCard } from "@finisai/medusa-payment-moka"

const kart = getTestCard({ bank: "Garanti Bankasi" })
const troyKarti = getTestCard({ cardType: "Troy" })

Testler

npm install
npm test
npm run typecheck

Testler ağ bağlantısı gerektirmez; HTTP katmanı sahte taşıma (transport) ile taklit edilir. Test paketi 36 test kartının tamamını hem istemci isteklerinden hem de sağlayıcının 3D başlatma + callback doğrulama akışından geçirir.

npm Yayınlama

Paket, publish öncesinde otomatik olarak derlenir ve testler çalıştırılır (prepublishOnly betiği). Yayınlamak için:

npm login
npm publish

Yeni sürüm çıkarırken önce sürüm numarasını artırın:

npm version patch   # veya minor / major
npm publish

Lisans

MIT lisansı ile dağıtılmaktadır. Ayrıntılar için LICENSE dosyasına bakınız.