Sanal POS API Entegrasyonu: Geliştiriciler İçin Hızlı Başlangıç

Web sitenize veya uygulamanıza sanal POS entegre etmek, online ödeme almanın en esnek ve güçlü yoludur. API entegrasyonu sayesinde ödeme akışını tamamen kontrol edebilir, özel iş kuralları tanımlayabilir ve müşterilerinize sorunsuz bir ödeme deneyimi sunabilirsiniz.

Bu yazıda sanal POS API entegrasyonunun genel yapısını, başlangıç adımlarını, 3D Secure akışını, webhook entegrasyonunu ve test sürecini geliştiriciler için anlaşılır bir şekilde özetliyoruz. Detaylı teknik dokümantasyon ve örnek kodlar için geliştirici sayfalarımıza yönlendirmeler yapacağız.

API Entegrasyonuna Başlamadan Önce

Sanal POS API entegrasyonuna başlamadan önce aşağıdaki gereksinimlerin hazır olduğundan emin olun:

• HTTPS destekli sunucu: API iletişimi ve ödeme sayfası için SSL sertifikası zorunludur. Tüm veriler şifreli olarak iletilmelidir.
• Geliştirme ortamı: Tercihinize göre PHP, Node.js, Python, C#, Java veya başka bir dil ile geliştirme yapabilirsiniz.
• Onaylanmış hesap: Sanal POS sağlayıcınızda hesap oluşturmuş ve başvurunuz onaylanmış olmalıdır.
• API dokümantasyonu: Sağlayıcınızın API dokümantasyonunu okuyun. Uç noktalar (endpoints), istek ve yanıt formatları, hata kodları ve kimlik doğrulama yöntemi hakkında bilgi edinin.

API Anahtarlarını Alma

API anahtarları, sanal POS sağlayıcınızla güvenli iletişim kurmanızı sağlayan kimlik bilgileridir. Genellikle iki tür API anahtarı bulunur:

• Public Key (Açık Anahtar): İstemci tarafında (frontend) kullanılır. Ödeme formu oluştururken veya kart bilgilerini tokenize ederken kullanılır.
• Secret Key (Gizli Anahtar): Sunucu tarafında (backend) kullanılır. Ödeme başlatma, sorgulama, iptal ve iade gibi işlemler için kullanılır. Bu anahtarı asla istemci tarafında paylaşmayın.

API anahtarlarınızı kontrol panelinden alabilirsiniz. Her ortam (test ve canlı) için ayrı API anahtarları sağlanır. Geliştirme aşamasında test anahtarlarını, canlıya geçtiğinizde canlı anahtarları kullanın.

İlk API Çağrısı: Basit Ödeme Başlatma

API anahtarlarınızı aldıktan sonra ilk ödeme isteğinizi gönderebilirsiniz. Tipik bir ödeme başlatma akışı şu şekilde çalışır:

1. Ödeme bilgilerini hazırlayın: Tutar, para birimi, sipariş numarası, müşteri bilgileri ve geri dönüş URL'leri gibi verileri hazırlayın.
2. API isteğini gönderin: POST metodu ile ödeme başlatma endpoint'ine JSON formatında istek gönderin. İsteğe API anahtarınızı header olarak ekleyin.
3. Yanıtı işleyin: API'den dönen yanıtta ödeme sayfası URL'si veya 3D Secure yönlendirme bilgisi yer alır. Müşteriyi bu sayfaya yönlendirin.
4. Sonucu alın: Ödeme tamamlandığında müşteri callback URL'inize yönlendirilir ve webhook ile işlem sonucu sunucunuza bildirilir.

API isteği ve yanıtının detaylı formatı, parametrelerin açıklaması ve hata kodları için geliştirici dokümantasyonumuzu inceleyin.

3D Secure Akışı

Türkiye'de online kart işlemlerinde 3D Secure doğrulaması zorunludur. API entegrasyonunda 3D Secure akışını doğru şekilde uygulamak kritik önem taşır. Akış şu şekilde çalışır:

1. Ödeme başlatma isteği gönderin: 3D Secure parametrelerini ve callback URL'lerinizi içeren ödeme isteği gönderin.
2. 3D Secure HTML'ini alın: API yanıtında bankanın 3D Secure doğrulama sayfasına yönlendirme için HTML içeriği döner.
3. Müşteriyi yönlendirin: Dönen HTML'i müşterinin tarayıcısında render edin. Müşteri bankanın doğrulama sayfasına yönlendirilir.
4. Doğrulama tamamlanır: Müşteri SMS kodu, mobil uygulama onayı veya biyometrik doğrulama ile kimliğini kanıtlar.
5. Callback URL'ine dönüş: Doğrulama sonrası müşteri belirlediğiniz callback URL'ine yönlendirilir. Bu URL'de dönen parametreleri alarak ödeme sonucunu kontrol edin.

Webhook Entegrasyonu

Webhook, ödeme işleminin sonucunu sunucunuza otomatik olarak bildiren HTTP callback mekanizmasıdır. Webhook entegrasyonu şu nedenlerle kritik önem taşır:

• Güvenilir sonuç kaynağı: Müşteri tarayıcıyı kapatsa veya internet bağlantısı kopsa bile, webhook üzerinden ödeme sonucunu alırsınız.
• Asenkron bildirim: Ödeme tamamlandığında sunucunuz anında bilgilendirilir ve sipariş durumunu otomatik olarak güncelleyebilirsiniz.
• Çapraz kontrol: Callback URL'ine gelen bilgilerle webhook bildirimini karşılaştırarak işlem sonucunu doğrulayabilirsiniz.

Webhook endpoint'inizi oluştururken dikkat etmeniz gerekenler:

• HTTPS üzerinden erişilebilir bir URL olmalıdır.
• Gelen isteğin imzasını (signature) doğrulayarak isteğin gerçekten sağlayıcınızdan geldiğini kontrol edin.
• HTTP 200 yanıtı döndürün. Aksi halde sağlayıcı bildirimi yeniden göndermeyi deneyebilir.
• İdempotent (tekrar edilebilir) olarak tasarlayın. Aynı bildirim birden fazla kez gelebilir.

Test ve Hata Ayıklama

Canlıya geçmeden önce kapsamlı testler yapmanız büyük önem taşır. Sandbox test ortamında şu senaryoları mutlaka deneyin:

• Başarılı ödeme: Test kart numarası ile standart bir ödeme işlemini tamamlayın.
• Başarısız ödeme: Yetersiz bakiye ve geçersiz kart senaryolarını test edin.
• 3D Secure başarılı/başarısız: Doğrulama başarılı ve başarısız senaryolarını deneyin.
• Farklı taksit sayıları: Peşin, 3, 6, 9 ve 12 taksitli ödeme senaryolarını test edin.
• İptal ve iade: Başarılı bir ödemenin iptal ve iade işlemlerini deneyin.
• Webhook testi: Webhook bildirimlerinin doğru alındığını ve işlendiğini doğrulayın.
• Hata yönetimi: API'den dönen hata kodlarını yakalayın ve kullanıcıya anlamlı mesajlar gösterin.

Sonuç

Sanal POS API entegrasyonu, online ödeme almanın en esnek ve güçlü yoludur. RESTful API'ler, hazır SDK'lar ve kapsamlı sandbox test ortamları sayesinde entegrasyon süreci her geçen gün daha da kolaylaşmaktadır.

Bu yazıda API entegrasyonunun genel akışını, temel adımlarını ve dikkat edilmesi gereken noktaları özetledik. Detaylı teknik dokümantasyon, örnek kodlar ve entegrasyon rehberleri için geliştirici sayfalarımızı ziyaret edebilirsiniz.