Ödeme API anahtarı, PIN'i olmayan bir nakit kart gibi çalışır. Onu gönderen herkes fatura oluşturabilir, ödeme verilerinizi okuyabilir ve çıkış ödemesi (payout) kullanıyorsanız bakiyenizden para transferi yapabilir. Bu nedenle ödeme API güvenliği üç alışkanlığa iner: anahtarı kendi sunucularınızda tutmak, API'nin anahtarı yalnızca bu sunucuların adreslerinden kabul etmesini sağlamak ve her webhook'u, harekete geçmeden önce ödemeyi geri okuyarak doğrulamak.
Bu rehber, euro cinsinden hesaplaşan bir kripto ödeme API'sine bağlanan ödeme hizmet sağlayıcıları (PSP), elektronik para kuruluşları (EMI), bankalar ve işletmelerin mühendislik liderleri ve ödeme birimi yöneticileri içindir. Anahtarın bir IP adresi ve CIDR aralığıyla nasıl kısıtlanacağını, anahtarın nerede tutulması gerektiğini, webhook'ların nasıl kontrol edileceğini ve çıkış ödemelerinin çevresinde hangi kontrollerin bulunması gerektiğini gösterir. Örneklerde ItisPay API'si ve kontrol paneli kullanılmaktadır (demo veriler).
Önemli anlar
Kısaca
- Bir API anahtarı, taşıyıcı bir kimlik bilgisidir (bearer credential). GitGuardian, 2025'te herkese açık GitHub commit'lerinde 28,65 milyon yeni gömülü (hardcoded) gizli bilgi saptadı; bu nedenle yalnızca anahtarı güvende tutmayı değil, sızmasını da planlayın.
- Bir IP izin listesi, sızan bir anahtarı ağınızın dışında işe yaramaz hale getirir. Gerçek giden adreslerinizi kapsayan en küçük IPv4 veya IPv6 aralıklarını listeleyin; boş bir liste her adrese izin verir.
- Webhook bir bildirimdir, kanıt değildir. Mal göndermeden veya bir hesabı alacaklandırmadan önce faturayı kimliğiyle ve anahtarınızla yeniden okuyun.
- Çıkış ödemeleri (payout) tarafınızda insan kontrolleri gerektirir: iki adımlı oturum açma, kayıtlı alıcı IBAN'ları ve cüzdanlar ile belirli bir tutarın üzerindeki işlemler için ikinci bir onaylayıcı.
Sızdırılan bir ödeme API anahtarı neden bu kadar tehlikelidir?#
Sızdırılan bir ödeme API anahtarı tehlikelidir, çünkü anahtar entegrasyonunuzun tüm kimliğidir. Çoğu ödeme API'si gibi ItisPay API de her isteği tek bir başlıkla, Api-key ile doğrular; aynı kimlik doğrulama faturaları, bir IBAN veya cüzdana yapılan çıkış ödemelerini ve harici bir adrese yapılan kripto çekimlerini kapsar. Dokümantasyonun anahtarın “istemci tarafı kodda veya herkese açık depolarda açığa çıkmamasını” istemesinin nedeni de budur.
Pratikte anahtarlar sıradan yerlerden sızar: kod, günlükler ve sohbetler. GitGuardian'ın State of Secrets Sprawl 2026 raporuna göre (Mart 2026), 2025'te herkese açık GitHub commit'lerine eklenen yeni gömülü gizli bilgi sayısı 28,65 milyon oldu; bu, bir önceki yıla göre %34 daha fazlaydı. GitGuardian, 2022'de sızmış gizli bilgileri yeniden test ettiğinde, bunların %64'ünden fazlasının Ocak 2026'da hâlâ geçerli olduğunu gördü. Ekipler anahtarları yayımlayıp sonra değiştirmeyi unutuyor.
OWASP API Güvenlik İlk 10 listesi (2023), “Bozuk Kimlik Doğrulama”yı ikinci sıraya koyar ve “kimlik doğrulama mekanizması herkese açık olduğu için saldırganlar için kolay bir hedeftir” diye uyarır. Verizon'un 2025 Data Breach Investigations Report raporu, kimlik bilgisi kötüye kullanımını %22 oranıyla en yaygın ilk saldırı vektörü olarak gösterir. Yalnızca gizli bir dize zayıf bir savunmadır; bu nedenle bu rehberin geri kalanı, dize sızdıktan sonra da geçerli kalan katmanlar ekler.
Bir IP izin listesi API anahtarını nasıl korur?#
Bazen IP beyaz listesi olarak da anılan bir IP izin listesi, anahtarı yalnızca bir dizeye değil, yerlere de bağlayarak korur. API, anahtarı yalnızca istek listelediğiniz bir adresten geldiğinde kabul eder; geliştiricinin dizüstü bilgisayarındaki, bir CI günlüğündeki veya bir yapıştırma (paste) sitesindeki anahtar kopyası çalışmaz.
ItisPay kontrol panelinde bu ayar Projects, ardından Settings, ardından Security altında, “API Allowed IPs” alanında yer alır. Alan, virgülle ayrılmış tek adresler ve CIDR blokları listesi alır. Yardım metni şöyle der: “Tüm IP'lere izin vermek için boş bırakın. Hem IPv4 hem de IPv6 desteklenir.” Aynı liste, proje API üzerinden oluşturulurken api_allowed_ips alanında da ayarlanabilir; 256.256.256.256 gibi geçersiz bir girdi ise kaydedilmek yerine bir doğrulama hatasıyla reddedilir.
Boş varsayılan değer önemlidir. Yeni bir proje, biri alanı doldurana kadar anahtarını her yerden kabul eder; bu yüzden bu adımı canlıya alma kontrol listesine ekleyin, sonradan düzenlenecekler listesine değil. Ekran görüntüsündeki demo değerler olan 203.0.113.10 ve 198.51.100.0/24, RFC 5737'nin dokümantasyon için ayırdığı aralıklardan gelir; sizin listeniz kendi herkese açık adreslerinizi içerecektir. Her projenin kendi 64 karakterlik anahtarı ve kendi listesi vardır; böylece canlı ortam iki veya üç sunucuyla kilitli kalabilirken bir test projesi daha geniş bir küme kabul edebilir.
IPv4 ve IPv6 için CIDR aralıkları nasıl yazılır?#
Sunucularınızın API'ye ulaşmak için gerçekten kullandığı her adresi kapsayan en küçük aralığı yazın. İzin listesiyle ilgili sorunların çoğu, çok geniş bir aralıktan ya da birinin unuttuğu bir giden yoldan kaynaklanır.
Bir önekin okunması#
Bir CIDR bloğu, bir adresin ardından eğik çizgi ve önek uzunluğunun gelmesiyle oluşur. RFC 4632, önek uzunluğunu anlamlı bit sayısı olarak tanımlar: 192.168.99.0/24, ilk 24 biti sabitler ve geriye kalan 8 biti serbest bırakır; bu da 256 adres eder. Önekten çıkardığınız her bit bloğu iki katına çıkarır. Bir /32 tek bir IPv4 adresidir; /29 ise 8 adres, /24 ise 256 adres eder ve /16 ise 65.536 adrestir.
IPv6 de aynı şekilde 128 bit ile çalışır. Bir /128 tek bir adrestir. RFC 4291, çoğu IPv6 adresinin arayüz kısmını 64 bit olarak belirler; bu nedenle bir sunucunun ağı normalde bir /64'tür ve ana bilgisayar, örneğin işletim sistemi geçici adresler ürettiğinde, bu ağ içinde adresini değiştirebilir. Ana bilgisayarınızın IPv6 adresi değişiyorsa ve bu /64 yalnızca size aitse, tek bir /128 yerine /64'ü listeleyin. IPv6 örnekleri için dokümantasyon aralığı 2001:db8::/32'dir (RFC 3849); bu nedenle bunu asla gerçek bir izin listesine kopyalamayın.
Gerçek giden adresinizi bulmak#
Önemli olan, sunucunuzun kendisi hakkında bildirdiği adres değil, API'nin gördüğü adrestir. Bir bulut NAT ağ geçidinin ya da kurumsal bir güvenlik duvarının arkasında, birçok makine bir veya iki herkese açık adresi paylaşır. Sunucusuz işlevler, sabit bir çıkış yoluna yönlendirmediğiniz sürece genellikle ortak bir havuzdan çıkar. Her ortamı, “IP adresim nedir” gibi bir servisi çağırarak kontrol edin veya güvenlik duvarı günlüklerinizdeki kaynak adresi okuyun, ardından tam olarak bu adresi listeleyin.
| Kurulum | Ne listelenmeli | Sonuç |
|---|---|---|
| Statik genel IPv4 adresine sahip tek bir sunucu | Bu adres, /32 olarak ya da düz biçimde | Çalışır |
| Bulut NAT ağ geçidinin arkasındaki birden fazla sunucu | NAT ağ geçidinin genel adresleri | Çalışır |
| Değişen adresli IPv6 ana bilgisayarı | Ana bilgisayarın /64 bloğu, başka kimse kullanmıyorsa | Duruma bağlı |
| Manuel test için ofis ağı | Sağlayıcı garanti ediyorsa ofisin sabit adresi | Duruma bağlı |
| Sabit çıkış adresi olmayan sunucusuz fonksiyonlar | Önce bunları sabit adresli bir NAT üzerinden yönlendirin | Hayır |
| Bir bulut sağlayıcısının tüm bölgesel aralığı | Hiçbir şey; diğer müşterileri de kapsar | Hayır |
Bir değişikliği kaydetmeden önce yeni adresi ekleyin, dağıtımı yapın, trafiğin aktığını doğrulayın ve yalnızca bundan sonra eski adresi kaldırın. Canlı sunucularınızı dışarıda bırakan bir listeyi kaydetmek, kendi ödeme sayfanızı engeller.
API anahtarı nerede tutulmalı ve kim görebilir?#
Anahtar yalnızca sunucularınızda, bir gizli bilgi deposunda bulunmalı; başka hiçbir yerde olmamalı. Tarayıcı sayfasının ya da mobil uygulamanın içine asla koymayın; orada herkes okuyabilir. Anahtarı URL'lere de koymayın: OWASP REST Güvenlik Özet Kılavuzu, URL içindeki bir anahtarın web sunucusu günlüklerinde ele geçirilebileceği konusunda uyarıyor. Ödeme sayfanız arka uç sisteminizle konuşur; arka uç ise ödeme API'siyle konuşur.
Anahtarı başlangıçta bir gizli bilgi yöneticisinden ya da ortam değişkenlerinden yükleyin; depodaki bir yapılandırma dosyasından değil. Kodunuzu GitHub'da barındırıyorsanız push koruması özelliğini açın: GitHub belgelerine göre, “push girişimi sırasında olası bir gizli bilgi tespit ederse push'u engeller.”
Ortam başına bir anahtar tutun. Her ItisPay projesi kendi anahtarını ve izin listesini taşır; dolayısıyla canlı ve test ortamları için ayrı projeler kullanmak, sızmış bir test anahtarının canlı ödemelere dokunamayacağı anlamına gelir. Üretim anahtarını görebilecek kişileri sınırlayın. EBA'nın 2019 tarihli BİT güvenliği kılavuzu, teknik kullanıcılar dahil olmak üzere “bilmesi gereken” erişim ilkesini ve “asgari erişim haklarını” kural olarak koyar; 2025'ten itibaren DORA, bu yükümlülüğü çoğu ödeme kuruluşu için kapsar.
Sonra, ihtiyaç duymadan önce, anahtarı nasıl değiştireceğinizi yazılı olarak belirleyin. OWASP Kriptografik Depolama Özet Kılavuzu, anahtarların belirli bir süre sonra ve bir ele geçirilme şüphesi olduğunda değiştirilmesini (döndürülmesini) öneriyor ve “bir anahtarı döndürmek için gereken kodun ve süreçlerin, ihtiyaç duyulmadan önce hazır olmasını” şart koşuyor.
Bir ödeme API'sinden gelen webhook'lar nasıl doğrulanmalı?#
Bir webhook'u, bir şeyin değiştiğine dair bir bildirim olarak ele alın; asla ödemenin alındığına dair kanıt olarak değil. Geri çağırma URL'nizi öğrenen herkes, oraya sahte bir “tamamlandı” mesajı gönderebilir. Güvenli yöntem, faturayı kendi anahtarınızla API'den yeniden okumak ve API'nin döndürdüğü veriye göre hareket etmektir.
ItisPay faturası oluşturduğunuzda, callback_url alanı durum güncellemeleri için adresi belirler. Bir webhook geldiğinde, ondan fatura kimliğini alın, faturayı kimliğiyle GET isteğiyle sorgulayın ve yalnızca bu yanıt beklediğiniz durumu ve fiyatlandırdığınız tutarı gösteriyorsa teslimat yapın veya hesaba kredi aktarın. Belgelere göre bu uç nokta, ödeme durumunu ve blokzincir ayrıntılarını “kullanıcılara gösterim veya doğrulama için” döndürür.
Bir dizi kural işleyiciyi temiz tutar:
- Webhook'ları yalnızca HTTPS üzerinden kabul edin; düz HTTP isteklerini reddedin.
- İşleyiciyi idempotent yapın. İşlenen her fatura kimliğini ve durumunu saklayın ve tekrarları atlayın; çünkü sağlayıcılar bildirimleri yeniden gönderir.
- Hızlı yanıt verin ve işi bir kuyrukta yapın; böylece yavaş bir veritabanı yeniden denemeleri tetiklemez.
- Bir sağlayıcı webhook'larını RFC 2104'te tanımlanan anahtarlı bir karma olan HMAC ile imzalıyorsa, imzayı yeniden hesaplayın ve sabit süreli bir fonksiyonla karşılaştırın. OWASP Webhook Güvenliği Özet Kılavuzu açık sözlüdür: “Asla == kullanmayın: zamanlama bilgisi sızdırır ve uç noktayı bir imzalama orakulumuna dönüştürebilir.” Damgalı zamanı çok eski olan mesajları reddedin.
Canlıya geçmeden önce test edin. ItisPay, gerçek bir test faturasında bir durum değişikliğini simüle eden bir uç nokta ve bir fatura ya da sipariş kimliği için en son webhook'u yeniden gönderen başka bir uç nokta sunar; böylece gerçek para kullanmadan yeniden denemeleri ve tekrarları kontrol edebilirsiniz.
Ödemeleri ve kontrol paneli erişimini nasıl kilitlersiniz?#
Çalınan bir anahtarın para kaybına dönüştüğü yer ödemelerdir; bu yüzden etrafına insan kontrolleri ekleyin. ItisPay ödeme (payout) uç noktası üzerinden, fiat ödemesi bir yararlanıcı IBAN'ına, kripto ödemesi ise bir cüzdan adresine, her ikisi de kullanılabilir bakiyenizden gönderilir. API, isteğin dediğini yapar; bir isteğin meşru olup olmadığına karar vermek ise sizin işinizdir.
Sizin tarafınızda işe yarayan kontroller:
- Kontrol paneli veya ödeme yetkisi olan herkes için iki adımlı oturum açma. AB ödeme mevzuatı bu fikri ödeme kullanıcıları için zaten kullanıyor: güçlü müşteri kimlik doğrulamasına ilişkin PSD2 kuralları, bilgi, sahip olma ve içkinlik unsurlarından en az iki bağımsız unsur gerektiriyor. Aynı standardı kendi personeliniz için de uygulayın.
- Kayıtlı yararlanıcılar. Onaylanmış IBAN'ların ve cüzdan adreslerinin kendi listenizi tutun ve ödeme hizmetinizin yalnızca bu listedeki kayıtlara gönderim yapmasına izin verin. Yeni bir yararlanıcı ayrı bir onaydan geçmeli; ideal olarak bir soğuma süresiyle birlikte.
- Bir eşiğin üzerindeki işlemler için ikinci onaylayıcı. Bir kişi hazırlar, diğeri onaylar. Tutarı kendi risk iştahınıza göre belirleyin.
- Ayrı bir ödeme hizmeti. Ödemeleri, faturaları oluşturan ödeme sunucularından ayrı olarak, izin listesinde kendi sabit adresiyle çalışan tek bir hizmetten yürütün.
| Kontrol | Neyi durdurur | Karar |
|---|---|---|
| Anahtarda IP izin listesi | Sızmış bir anahtarın ağınızın dışından kullanılması | Çalışır |
| Anahtar yalnızca sunucuda | Tarayıcılardan, uygulamalardan ve depolardan anahtar çalınması | Çalışır |
| Webhook sonrası faturanın yeniden okunması | Sahte “ödendi” bildirimleri | Çalışır |
| Kayıtlı alıcılar ve ikinci onaylayıcı | Ödemelerin saldırganın IBAN'ına ya da cüzdanına yapılması | Çalışır |
| Listedeki ele geçirilmiş bir sunucuya karşı yalnızca bunlardan biri | İçeride zaten bulunan biri tarafından çalma | Hayır |
DORA ve PCI DSS API erişiminden ne bekliyor?#
Düzenlenmiş bir AB finans kuruluşuysanız, bu kontroller isteğe bağlı ek önlemler değildir. Dijital Operasyonel Dayanıklılık Tüzüğü (DORA, (AB) 2022/2554 sayılı Tüzük), EBA'ya göre 17 Ocak 2025'ten beri uygulanmaktadır. Bu Tüzüğün 9. maddesi, firmalardan BİT varlıklarına erişimi “fiziksel veya mantıksal olarak sınırlayan politikalar uygulamalarını” ve “güçlü kimlik doğrulama mekanizmaları için politika ve protokoller uygulamalarını” ister. Yalnızca sunucuda tutulan, izin listesine alınmış ve döndürme planı olan bir anahtar, bir denetçinin görmek isteyeceği türden kanıttır.
PCI DSS kart verilerini kapsar, kripto faturalarını değil. Aynı ekip kart ödemeleri de yürütüyorsa, 8.4.2 numaralı gereklilik kart sahibi veri ortamına yapılan tüm erişimlerde çok faktörlü kimlik doğrulama ister ve 4.0 sürümünün ileri tarihli gereklilikleri 31 Mart 2025'te zorunlu hale geldi.
Ödeme API güvenlik kontrolleri nerede işe yaramaz hale gelir?#
Bu kontroller giriş yollarını daraltır. Tek başlarına bir entegrasyonu güvenli kılmazlar. Webhook gönderenler için bile OWASP webhook kılavuzu IP izin listesini “yalnızca ek bir katman” olarak niteler, çünkü “paylaşılan bir çıkış IP adresi kimlik kanıtı değildir.”
Nerede yardımcı olmaz
- İzin listesindeki ele geçirilmiş bir sunucu. Saldırgan, gerçek anahtarla güvenilir bir adresten istek gönderir.
- Paylaşılan çıkış adresleri. Diğer kiracılar aynı NAT adresinden bulut ortamını terk ediyorsa, izin listesi onları sizden ayıramaz.
- İki adımlı oturum açma olmadan çalınan bir kontrol paneli parolası. Saldırgan API'yi tamamen atlar.
- Fatura alanlarındaki kişisel veriler. ItisPay'in herkese açık fatura uç noktası, açık faturalar için anahtar olmadan tam ayrıntıları döndürür; bu yüzden müşteri adlarını ve e-posta adreslerini sipariş adının dışında tutun.
Güvenli bir entegrasyona bir öğleden sonrada nasıl başlarsınız?#
Sabit bir sırayı izlerseniz, güvenli bir entegrasyonun teknik kısmını bir öğleden sonrada tamamlayabilirsiniz. Aşağıdaki adımlarda ItisPay kullanılmıştır; aynı sıra herhangi bir sağlayıcıyla da işe yarar.
- Bir test projesi ve her biri kendi anahtarına sahip ayrı bir canlı proje oluşturun.
- Her iki anahtarı da gizli bilgi yöneticinizde saklayın ve yalnızca sunucuda yükleyin.
- Her ortamın herkese açık çıkış adresini bulun ve API Allowed IPs alanına girin.
- Faturayı arka uçtan oluşturun: Api-key başlığıyla https://api.itispay.com/api/v1/invoices adresine POST gönderin; benzersiz bir order_id, fiat_currency olarak EUR ile bir fiat_amount, currency alanında kripto para birimi ve callback_url'nizi ekleyin.
- Webhook işleyicisini oluşturun: yalnızca HTTPS, idempotent, herhangi bir işlemden önce faturayı ID ile yeniden okuyan.
- İşlediğiniz her durum için webhook simülasyonunu, ardından yinelenenleri test etmek için yeniden gönderme uç noktasını çalıştırın.
- Ödemeleri en son açın; kayıtlı alıcılar ve ikinci bir onaylayıcıyla birlikte.
Hızlı başlangıç için, kontrol panelindeki Ask AI asistanı istek üzerine örnek kod yazar; örneğin Api-key başlığı yerinde olacak şekilde Node.js'te bir fatura çağrısı gibi. Bunu taslak olarak değerlendirin: göndermeden önce alan adlarını API referansıyla karşılaştırın, çünkü sözleşme oluşturulmuş bir örnek değil, referanstır. ItisPay ayrıca npm üzerinde resmi bir TypeScript istemcisi yayımlıyor: @itispay/typescript-client.
Bunu daha geniş bir ödeme orkestrasyonu kurulumuna bağlıyorsanız, her sağlayıcıya kendi anahtarını, izin listesini ve webhook işleyicisini verin. ID ile yeniden okunan aynı kayıt, finans ekibiniz için kripto ödeme mutabakatını da besler.
Stablecoin ödemeleri kabul etmek ve yığını kendiniz kurmadan euro almak istiyorsanız, ItisPay API'yi, faturalandırmayı, webhook'ları ve mutabakatı sağlar; ayrıca API güvenliğinin ilk katmanını da sunar: kendi IP adreslerinizle sınırlayabileceğiniz anahtarlar. Lisanslama, KYC ve IBAN'ınıza yapılan takas/uzlaşma (settlement) işlemleri, AB lisanslı kripto varlık hizmet sağlayıcısı (CASP) + Ödeme Kuruluşu ortağımız aracılığıyla yürütülür ve çoğu ekip KYB'den ilk işleme bir haftadan kısa sürede geçer.
Bu makale yalnızca bilgilendirme amaçlıdır ve hukuki veya düzenleyici tavsiye niteliği taşımaz.
