Python ile Sanal POS Entegrasyonu

Neden Python ile Ödeme Entegrasyonu?

Python, okunabilir sözdizimi ve geniş kütüphane desteği sayesinde ödeme entegrasyonunu anlaşılır bir işe dönüştürür. Web tarafında Django, Flask ve FastAPI gibi olgun framework'ler bulunur ve üçü de ödeme akışının ihtiyaç duyduğu parçalara sahiptir: sunucudan istek göndermek, kart sahibini doğrulama adımına yönlendirmek, dönen bildirimi karşılayıp kendi kaydınıza işlemek.

Entegrasyonun büyük bölümü birkaç REST çağrısından oluşur. requests gibi bir HTTP istemcisiyle ödeme başlatma isteği birkaç satır kodla yazılır; dönen yanıt sözlük yapısına çevrilip doğrudan kullanılabilir. Bu yalınlık, Django ile kurulmuş kapsamlı bir e-ticaret projesinde de, Flask ile yazılmış hafif bir mikroserviste de akışın aynı kalmasını sağlar.

Python'un veri tarafındaki ekosistemi, ödeme kayıtlarınızı sonradan incelemek istediğinizde işe yarar. Panelden ya da raporlama çağrılarından aldığınız işlem kayıtlarını pandas ile filtreleyebilir, matplotlib veya seaborn ile görselleştirebilirsiniz. Hangi raporlama çağrılarının hesabınıza tanımlı olduğu ve dışa aktarım biçimleri seçilen çözüme göre değişir.

Asenkron çalışan projeler için de engel yoktur. asyncio ile çalışan bir HTTP istemcisi kullanıldığında ödeme çağrıları FastAPI veya aiohttp tabanlı bir uygulamanın içinden de gönderilebilir. Hazır paketin senkron ve asenkron kapsamı ile desteklenen Python sürümleri dokümantasyonunuzda belirtilir.

Kod Örneği

Aşağıdaki örnek, Python ve requests kütüphanesi ile REST üzerinden bir ödeme isteğinin nasıl gönderildiğini gösterir. Hazır paket kullanacaksanız kurulum bağımlılık yöneticisiyle yapılır; aşağıdaki paket adı yer tutucudur, gerçek ad ve komut hesabınız açıldığında iletilen dokümantasyonda belirtilir.

# Paket adı hesabınız açıldığında iletilen dokümantasyonda yazılıdır.
# Tahmin ettiğiniz bir adla kurulum yapmayın (sahte paket riski).
pip install <dokumantasyondaki-paket-adi>

Paket kullanmak zorunlu değildir. Aynı işlem yalnızca bir HTTP istemcisiyle de yapılabilir; bu durumda imzalama ve hata yönetimini kendi tarafınızda kurarsınız. Aşağıdaki çağrıda adres ve alan adları örnektir.

Kart numarasını kendi formunuzla alıp sunucunuzdan gönderirseniz kart verisi işleyen taraf olursunuz ve PCI DSS yükümlülüğünüz büyür; ödeme kuruluşunun ödeme sayfası ya da iframe’i kullanıldığında kart bilgisi sunucunuza ulaşmaz.

import os
import requests

# Anahtarı kod deposuna yazmayın; sunucu ortam değişkeninde tutun
API_KEY = os.environ['SANALPOS_API_KEY']

# adres ve alan adları dokümantasyonunuzda
BASE_URL = 'https://API_ADRESI/v1'

def odeme_baslat(siparis):
    # Kart bilgisi bu isteğe eklenmez; müşteri kartını ödeme kuruluşunun
    # sayfasında ya da iframe'inde girer. Tutarı kendi kaydınızdan alın.
    response = requests.post(
        f'{BASE_URL}/payments',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'amount': siparis['tutar'],  # tutar biçimi (TL / kuruş) dokümantasyonunuzda
            'currency': 'TRY',
            'orderId': siparis['no'],
            'callbackUrl': 'https://siteadresiniz.com/odeme-sonuc',
        },
        timeout=15,
    )
    response.raise_for_status()
    return response.json()  # 3D Secure / ödeme sayfası yönlendirme adresini içerir

Bu örnek temel bir REST çağrısını gösterir; metot adları, zorunlu alanlar ve dönen durum kodları seçilen çözüme göre değişir. Tutar, para birimi ve sipariş numarası her zaman sunucuda belirlenir, tarayıcıdan gelen değere güvenilmez. Uç nokta ve alan referansı için API dokümantasyonu, Python'a özgü örnekler için Python SDK sayfasına bakın.

Framework Seçimi ve Ödeme Akışı

Akış hangi framework'te olursa olsun aynı sırayı izler. Ödeme isteği sunucudan oluşturulur, kart sahibi 3D Secure doğrulamasına yönlendirilir ve dönüşte sonuç sunucu tarafında doğrulanır. Django'da bu adımlar birer view ile, Flask'ta birer route ile, FastAPI'de birer endpoint ile karşılanır; değişen yalnızca yazım biçimidir.

Bildirim uç noktası ayrı bir adres olarak tanımlanır. Ödeme sonucu değiştiğinde sunucunuza bir istek gönderilir; siz önce imzayı doğrular, sonra sipariş durumunu güncelleyip 200 yanıtı dönersiniz. Aynı bildirim iki kez gelebileceği için kaydın idempotent güncellenmesi, yani ikinci gelişte çift kayıt oluşturmaması beklenir. Alan yapısı ve yeniden deneme davranışı webhook ve callback sayfasında açıklanır.

Anahtarlar kod dosyalarına ya da sürüm deposuna yazılmaz; sunucu ortam değişkenlerinde tutulur. Test ve canlı anahtarlar ayrı tutulur, canlı anahtarla test yapılmaz. Günlük kayıtlarında kart numarası, CVV ve API anahtarı bulunmamalıdır. Test senaryolarının nasıl çalıştırılacağı test ortamı (sandbox) sayfasında, dönen kodların karşılığı POS hata kodları sayfasında yer alır.

Akış test anahtarlarıyla doğrulandıktan sonra yalnız ortam ve anahtar değerleri canlıya çevrilir; kod yapısı aynı kalır. Entegrasyona başlamak için önce başvuru formunu doldurmanız yeterlidir; anahtarlar ve dokümantasyon erişimi hesap açılışıyla tanımlanır.

Teknik gereksinimler

Sürüm bilgileri genel çerçevedir; kesin gereksinimler ve desteklenen sürümler, hesabınız açıldığında iletilen dokümantasyonda belirtilir.