Geliştirici kaynakları

API Dokümantasyonu

Sanal POS entegrasyonunda API dokümantasyonu, ödeme isteğini nasıl göndereceğinizi ve dönen yanıtı nasıl yorumlayacağınızı tarif eden temel kaynaktır. Aşağıda dokümantasyona nasıl eriştiğinizi ve içinde hangi başlıkları bulacağınızı özetliyoruz.

REST ve JSON tabanlı istek/yanıt
Test ve canlı anahtarlar ayrı
Hata kodları ve doğrulama adımları belgelenir

Ücretsiz Başvuru → API yapısını görün ↓

Dokümantasyon erişimi, hesabınız açıldıktan sonra iletilir.

API'yi çalışacağınız ödeme kuruluşu sunar; uç noktalar, alan adları ve sürüm desteği seçilen çözüme göre değişir.

Dokümantasyonda ne var

Entegrasyon için gereken referans tek yerde.

Kimlik doğrulamadan ödeme akışına, hata kodlarından bildirimlere kadar entegrasyonu tamamlamak için gereken başlıklar dokümantasyonda yer alır.

Kimlik doğrulama

Hesaba özel anahtarlar
Test ve canlı ayrımı
İmza veya hash doğrulaması

Anahtarları istemci tarafında tutmayın; sunucu tarafında saklayın.

İstek ve yanıt biçimi

REST uç noktaları
JSON gövde ve alan adları
Tutar, para birimi ve sipariş numarası

Alan adları ve zorunluluklar seçilen çözüme göre değişebilir.

Hata kodları

İşlem sonucu kodları
Doğrulama ve yetki hataları
Yeniden deneme davranışı

Kod karşılıkları için POS hata kodları sayfasına bakın.

Dokümantasyonun adresi ve kapsamı, hesabınız açıldıktan sonra iletilir.

Ücretsiz Başvuru →Test ve entegrasyon çalışmalarında gerçek müşteri verisi kullanmayın. Ayrıntı için: KVKK Aydınlatma Metni.

Örnek istek

Ödeme isteğinizin biçimini görün.

Tutarın ve para biriminin hangi biçimlerde yazılabileceğini ve örnek bir istek gövdesini görün. Alan adları ve kabul edilen biçim kuruluşa göre değişir; kesin biçim hesabınızla gelen dokümantasyonda yazar.

Bazı kuruluşlar tutarı kuruş cinsinden tamsayı (34,56 TL → 3456), bazıları noktalı ondalık (34.56) ister; aynı kuruluşun farklı servisleri bile farklı biçim isteyebilir. Para birimi TRY, TL ya da ISO 4217 sayısal kodu 949 olarak yazılabilir (USD 840, EUR 978, GBP 826).

Tutar ve para birimi biçimleri
Biçim	Örnek
Noktalı ondalık	`1234.56`
Kuruş cinsinden tamsayı	`123456`
ISO 4217 harf kodu	`TRY`
ISO 4217 sayısal kod	`949`
Peşin için taksit değeri	`0` ya da `1` gibi; dokümantasyonda yazar

{
  "siparisNo": "S-20261001-0001",
  "tutar": "1234.56",
  "paraBirimi": "TRY",
  "taksit": 1,
  "dogrulama": "3D",
  "donusAdresi": "https://siteniz.example/odeme/donus",
  "bildirimAdresi": "https://siteniz.example/odeme/bildirim"
}

Alan adları yer tutucudur.

Gerçek alan adları, uç nokta ve anahtarlar hesap açılışında iletilir. Ödemeyi kim alacak?

Sık yapılan 4 hata

Tutarı yanlış birimle göndermek: 100 kat fazla ya da az çekim.
Aynı sipariş numarasını tekrar kullanmak.
Dönüş ya da bildirim adresini HTTPS dışında vermek.
Anahtarı istemci koduna (tarayıcı ya da mobil uygulama) koymak.

Sıradaki adım: örnek kodlar · imza deneme alanı · POS hata kodları

Sık sorulan sorular

API dokümantasyonu hakkında.

Dokümantasyona nasıl erişirim?

Başvurunuz tamamlanıp hesabınız açıldıktan sonra dokümantasyon erişimi ve anahtarlarınız iletilir. Adımlar için başvuru süreci sayfasına bakın.

API hangi biçimde çalışır?

Ödeme kuruluşlarının sanal POS servisleri genellikle REST uç noktaları ve JSON gövde kullanır. Uç nokta adresleri, alan adları ve sürüm desteği seçilen çözüme göre değişir; kesin bilgi dokümantasyonda yer alır.

Entegrasyonu canlıya almadan deneyebilir miyim?

Evet. Akışı önce test ortamı (sandbox) üzerinde çalıştırın; kart senaryoları için test kartları sayfasını kullanın.

Hata kodlarının karşılığını nereden görürüm?

Dönen kodların açıklamaları dokümantasyonda listelenir; yaygın karşılıklar için POS hata kodları sayfasına da bakabilirsiniz.

Hazır SDK veya kod örneği var mı?

Dil bazlı örnekler için örnek kodlar ve PHP, Node.js, Python sayfalarına bakın. SDK paketi ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir.

Entegrasyona başlayın

Önce başvurunuzu tamamlayalım.

Dokümantasyon ve anahtar erişimi hesap açılışıyla tanımlanır. Ön değerlendirme için başvuru formunu doldurun.

Ücretsiz Başvuru →

Başvuru ücretsizdir. Teklifi inceleyip karar verin.

Başvuru nasıl ilerler? →

Teknik sorularınız için:0212 909 00 87ya da WhatsApp’tan yazın

Ayrıntılar

Dokümantasyona Erişim

sanalpos.com başvurunuzu koordine eder; ödeme hizmetini ve API'yi anlaşma yaptığınız ödeme kuruluşu sunar. Bu nedenle dokümantasyonun adresi, erişim yöntemi ve kapsamı seçilen çözüme göre belirlenir ve hesabınız açıldıktan sonra size iletilir. Aynı aşamada test ve canlı anahtarlarınız da tanımlanır.

Entegrasyona başlamadan önce hangi ödeme yöntemlerini kullanacağınızı (tek çekim, taksit, 3D Secure doğrulaması, iade ve iptal) netleştirin; dokümantasyonda izleyeceğiniz bölümler bu seçime göre değişir. Genel akış için entegrasyon kılavuzu sayfasına bakabilirsiniz.

API'nin Genel Yapısı

Sanal POS servisleri yaygın olarak REST uç noktaları ve JSON gövde ile çalışır. Dokümantasyonda karşılaşacağınız başlıklar genellikle şunlardır:

Kimlik doğrulama: Hesabınıza tanımlanan anahtarlarla yapılır; test ve canlı anahtarlar ayrıdır. Birçok çözümde isteğin belirli alanlarından üretilen bir imza ya da hash değeri de gönderilir; sunucu bu değeri doğrulayarak isteğin yolda değiştirilmediğini kontrol eder. Anahtarları ve gizli değerleri yalnız sunucu tarafında saklayın, istemci koduna gömmeyin.
İstek biçimi: Tutar, para birimi, sipariş veya işlem numarası, ödeme yöntemi bilgisi ve dönüş adresleri gibi alanlar gönderilir. Zorunlu alanların adları ve biçimleri çözüme göre değişir.
Yanıt biçimi: İşlemin sonucu, kuruluşun ürettiği işlem kimliği ve sonuç kodu döner. Yanıtı kendi tarafınızda kaydedin; sipariş numarasıyla eşleştirmek sonraki sorgular ve mutabakat için gerekir.
Hata kodları: Doğrulama, yetki ve işlem reddi durumları ayrı kodlarla bildirilir. Kodların karşılığı için POS hata kodları sayfasına bakın.

Aynı sipariş için isteğin tekrar gönderilmesi ihtimaline karşı, kendi tarafınızda benzersiz bir sipariş numarası üretip mükerrer çekimi engelleyecek bir kontrol kurmanız önerilir.

Ödeme Akışının Adımları

Dokümantasyondaki örnekler çoğunlukla şu sırayı izler:

Müşteri ödeme adımına geldiğinde ödeme isteğini kendi sunucunuz üzerinden oluşturursunuz.
3D Secure kullanılıyorsa müşteri, kartını veren bankanın doğrulama ekranına yönlendirilir.
Doğrulama sonucu, önceden tanımladığınız dönüş adresine iletilir.
Sonucu sunucu tarafında doğrular, siparişi ancak başarılı yanıt aldıktan sonra onaylarsınız.
İade ve iptal gibi sonraki işlemler, ilk işlemden dönen işlem kimliğiyle yapılır.

Ödeme sonucunu sipariş sisteminize otomatik işlemek için bildirim akışını da kurabilirsiniz; alanlar ve doğrulama için webhook ve callback sayfasına bakın. Sonucu yalnız tarayıcıdan dönen veriye bakarak onaylamayın; her durumda sunucu tarafında doğrulayın.

Test Ortamı ve Kod Örnekleri

Akışı canlıya almadan önce test ortamı (sandbox) üzerinde uçtan uca çalıştırın; başarılı ve başarısız senaryolar için test kartları sayfasındaki senaryoları kullanın. Test ortamındaki işlemler gerçek para hareketine dönüşmez.

Dil bazlı hazır örnekler için örnek kodlar ile PHP, Node.js ve Python sayfalarına bakabilirsiniz. SDK paketi, kurulum komutu ve sürüm desteği, hesabınız açıldığında iletilen dokümantasyonda belirtilir. API entegrasyonunun genel çerçevesi için API ve SDK entegrasyonu sayfasına da göz atın.