Yapılandırma

Üretim kalitesinde entegrasyon için istemci yapılandırmasını standartlaştır.

Önerilen config yapısı

import { HsrcPay } from "@hsrcpay/sdk";

type Environment = "sandbox" | "production";

export function createHsrcPayClient(env: Environment) {
  return new HsrcPay({
    apiKey: env === "production" ? process.env.HSRCPAY_LIVE_KEY! : process.env.HSRCPAY_TEST_KEY!,
    environment: env,
    timeoutMs: 10_000,
    maxRetries: 2,
  });
}

Idempotency stratejisi

Yeniden denenen yazma işlemlerinde (create gibi) aynı isteğin iki kez çalışmasını önlemek için idempotency anahtarı kullanın. Confirm için ayrı zorunluluk tanımlı değilse bile timeout sonrası yeni payment açmak yerine payments.get ile mevcut kaydı kontrol edin.

const payment = await hsrcpay.payments.create(
  { amount: 8900, currency: "TRY" },
  { idempotencyKey: "order_2026_04_03_00042" },
);

İstek seviyesinde koruma

• Her yazma işleminde deterministic bir idempotencyKey üret.
• Uygulama içinde global timeout yerine endpoint-kritikliğine göre timeout belirle.
• Retry politikasını sadece geçici ağ/5xx hatalarında uygula.

Loglama ve gözlemlenebilirlik

• Request kimliği (requestId) ve paymentId gibi alanları structured log içine yaz.
• Başarısız çağrılarda HTTP status + hata kodu + correlation id sakla.
• Kişisel veri (PII) ve kart verisini loglara yazma.