En İyi Uygulamalar

Anahtar ve token

Saklanacak şey token değil, Ed25519 özel anahtarınızdır. Token 5 dakikada bir yenilenir; uygulamanız onu çalışırken basar.

• Özel anahtarı bir secrets manager'da ya da erişimi kısıtlı bir dosyada tutun
• Authorization başlığını asla loglamayın
• Anahtarı düzenli aralıklarla döndürün; şüphelenirseniz hemen iptal edin
• Yenisini yayına almadan eskisini iptal etmeyin — iptal anında o kid ile imzalanan istekler 401 almaya başlar

Token'ı önbelleğe alın

Her çağrıda yeni token basmak gereksiz yük ve gecikme üretir.

// ✅ Doğru — süresi dolana kadar tutun
let cached: { token: string; expiresAt: number } | null = null;
 
async function getToken() {
  const now = Math.floor(Date.now() / 1000);
  if (cached && cached.expiresAt - 30 > now) return cached.token;
  const t = await mintToken();
  cached = { token: t.access_token, expiresAt: t.expires_at };
  return cached.token;
}
 
// ❌ Yanlış — her istekte imzalayın ve token basın
async function handler() {
  const { access_token } = await mintToken();
}

30 saniyelik pay, çağrı yoldayken token'ın sona ermesini engeller.

Hata işleme

// ✅ Doğru
if (err.code === 'payment.card.declined') { … }
 
// ❌ Yanlış — çeviri değişince sessizce kırılır
if (err.message.includes('reddedildi')) { … }

• 500 · 502 · 503 · 504 → üstel geri çekilmeyle yeniden deneyin
• 400 · 401 · 403 · 409 · 422 → yeniden denemeyin, isteği düzeltin
• Her hatada dönen requestId'yi kendi loglarınıza yazın — destek talebinde tek anahtar o

Karardan önce hareket etmeyin

Fraud kararını parayı çekmeden önce alın. İşlem gerçekleştikten sonra sorulan soru denetim verisi üretir, koruma sağlamaz.

force_3d kararını uygulamak da bu kapsamdadır: sürtünmeyi yalnız riskli işlemde kullanmanın anlamı, düşük riskliyi 3DS'siz geçirip dönüşümü korumaktır.

Idempotency

Ödeme oluşturma çağrısını yeniden denerken aynı Idempotency-Key ile gönderin; aksi halde ikinci bir intent açarsınız.

Idempotency-Key: intent_<kendi işlem referansınız>

Anahtarı işleminize bağlayın, rastgele üretmeyin — yeniden denemede aynı değeri üretebilmeniz gerekir.

Webhook tüketimi

• İmzayı her zaman doğrulayın. v2 imzası ham gövdenin HMAC'idir — gövdeyi parse etmeden, ham byte'lar üzerinden doğrulayın. → Webhook'lar
• x-lunixi-event-id ile idempotent olun. Siz olayı işlemiş ama yanıtınız kaybolmuşsa aynı olay tekrar gelir.
• Uzun bakım penceresinde 5xx döndürmek yerine hızlıca 2xx dönüp işi kendi kuyruğunuza alın — art arda 20 hatada endpoint otomatik kapanır ve kendiliğinden açılmaz.

Tutarlar

Her üründe minör birim tam sayı. 250000 = ₺2.500,00.

Biz erişilemez olursak

Bunu önceden karara bağlayın; kesinti anında karar vermek istemezsiniz.

Kural yazmadan canlıya çıkmayın

Yapılandırılmamış merchant sessizce allow almaz: fraud.decision.unconfigured koduyla politika varsayılanı döner (tipik review). Canlıya çıkmadan önce akışınızı yayınlayın ve gölge modda gözlemleyin. → Akışlar ve Çözümleme

İlgili

• Kimlik Doğrulama — imzalama ve Step-Up
• Hata Yönetimi — zarf ve kodlar
• Webhook'lar — imza ve yeniden deneme