Geliştirici kaynakları

Python SDK

Python SDK, sanal POS ödeme akışını Django, Flask veya FastAPI gibi Python projelerinden yürütmek için kullanılan istemci kütüphanesidir. Aşağıdaki örneklerde geçen paket, modül ve metot adları yer tutucudur; gerçek adlar hesabınız açıldığında iletilen dokümantasyonda belirtilir.

Test ve canlı anahtarlar ayrı
Anahtarlar sunucu tarafında tutulur
Örnek akışlar test ortamında denenir

Ücretsiz Başvuru → Kurulum adımlarını görün ↓

SDK erişimi ve anahtarlarınız, hesabınız açıldıktan sonra tanımlanır.

Paket adı, sürüm desteği ve metot kapsamı çalışılacak ödeme kuruluşunun çözümüne göre değişir; hesabınız açıldığında iletilen dokümantasyonda belirtilir.

Python entegrasyonu

Ödeme akışını Python tarafında kurun.

SDK; ödeme isteği oluşturma, sonuç sorgulama ve bildirim doğrulama adımlarını Python projenizden yürütmenizi sağlar.

Kurulum ve anahtarlar

pip ile sanal ortama kurulum
API anahtarları ortam değişkeninde
Test ve canlı yapılandırma ayrı

Paket adı ve kurulum komutu, hesabınız açıldığında iletilen dokümantasyonda belirtilir.

Temel ödeme akışı

Ödeme isteği oluşturma
3D Secure yönlendirmesi
Sonuç sorgulama ve iade

Metot adları ve alanlar seçilen ödeme kuruluşunun çözümüne göre değişebilir.

Bildirim ve hata yönetimi

Webhook imza doğrulama
Tekrarlı bildirimde idempotency
Hata kodlarının karşılanması

Ödeme sonucunu yalnız sunucuya gelen bildirimle kesinleştirin.

SDK erişimi, test anahtarları ve dokümantasyon hesabınız açıldıktan sonra tanımlanır.

Ücretsiz Başvuru →Test ve günlük kayıtlarında gerçek kart verisi tutmayın. Ayrıntı için: KVKK Aydınlatma Metni.

Sık sorulan sorular

Python SDK hakkında.

Paketi nasıl kurarım?

Kurulum pip ile yapılır. Paketin adı, sürümü ve desteklenen Python sürümleri hesabınız açıldığında iletilen dokümantasyonda belirtilir; site içi özet için API dokümantasyonu sayfasına bakın.

Kodumu canlıya almadan deneyebilir miyim?

Evet. Test anahtarlarıyla test ortamı (sandbox) üzerinde çalışır, senaryoları test kartları ile denersiniz.

Ödeme sonucunu nasıl öğrenirim?

Sonuç, sunucunuza gelen bildirimle kesinleşir. İmza doğrulama ve tekrar eden bildirimlerin ele alınması için webhook ve callback sayfasına bakın.

Hata dönerse ne yapmalıyım?

SDK'nın ilettiği hata kodunu kullanıcıya gösterilecek mesajla eşleştirin. Karşılıkları için POS hata kodları sayfasını kullanın.

Canlıya geçerken ne değişir?

Yapılandırmadaki test anahtarları canlı anahtarlarla değiştirilir ve bildirim adresi canlı alan adınıza taşınır. Adımlar için entegrasyon kılavuzu sayfasına bakın.

Entegrasyona başlayın

Önce başvurunuzu tamamlayalım.

SDK erişimi ve anahtarlar 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

Kurulum ve Anahtar Yönetimi

Kurulum pip ile, tercihen projeye ait bir sanal ortamda yapılır. Paketin adı ve kurulum komutu, çalışılacak ödeme kuruluşunun çözümüne göre değişir ve hesabınız açıldığında iletilen dokümantasyonda belirtilir.

bash

python -m venv .venv
source .venv/bin/activate
# 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>

API anahtarlarını kaynak koda yazmayın; ortam değişkeninden okuyun ve sürüm kontrolüne eklemeyin. Test ve canlı anahtarları ayrı yapılandırmalarda tutun; böylece ortam değişimi tek bir değişkenle yapılır.

python

import os
# Modül ve sınıf adları yer tutucudur.
from sanalpos_sdk import Client

client = Client(
    api_key=os.environ["SANALPOS_API_KEY"],
    api_secret=os.environ["SANALPOS_API_SECRET"],
    environment=os.environ.get("SANALPOS_ENV", "test"),
)

Temel Ödeme Akışı

Tipik akışta sunucunuz bir ödeme isteği oluşturur, kullanıcıyı 3D Secure doğrulamasına yönlendirir ve doğrulama sonrası sonucu karşılar. Tutarı ve sipariş numarasını her zaman sunucu tarafında belirleyin; tarayıcıdan gelen tutara güvenmeyin.

python

odeme = client.payments.create(
    order_id="SIP-10234",
    amount="149.90",
    currency="TRY",
    callback_url="https://ornek-site.com/odeme/sonuc",
)

# 3D Secure yönlendirmesi için dönen adrese kullanıcıyı gönderin.
print(odeme.redirect_url)

İade, iptal ve sorgulama işlemleri de aynı istemci üzerinden çağrılır. Kullanılabilir metotlar, alan adları ve zorunlu parametreler seçilen ödeme kuruluşunun çözümüne göre değişir.

Webhook ve Hata Yönetimi

Ödeme sonucunu kullanıcının tarayıcısından dönen sayfayla değil, sunucunuza gelen bildirimle kesinleştirin. Bildirimin imzasını doğrulayın ve aynı sipariş için gelen tekrarlı bildirimlerde siparişi ikinci kez işlemeyin (idempotency).

python

@app.post("/webhook/odeme")
def odeme_bildirimi(request):
    if not client.webhooks.verify(request.body, request.headers):
        return Response(status=400)

    olay = client.webhooks.parse(request.body)
    if siparis_islendi_mi(olay.order_id):
        return Response(status=200)

    siparisi_isle(olay.order_id, olay.status)
    return Response(status=200)

Hata durumlarında SDK'nın ilettiği kodu günlüğe yazın; kart verisini ve anahtarları günlüğe yazmayın. Kodların karşılıkları için POS hata kodları sayfasını kullanın. Bildirim alanları ve doğrulama yöntemi için webhook ve callback sayfasına bakın.

Test ve Canlıya Geçiş

Akışı önce test ortamı (sandbox) üzerinde çalıştırın; başarılı ve başarısız senaryolar için test kartları sayfasındaki numaraları kullanın. Canlıya geçerken test anahtarları canlı anahtarlarla değiştirilir ve bildirim adresi canlı alan adınıza taşınır.

Adımların tamamı için entegrasyon kılavuzu ve API dokümantasyonu sayfalarına, hazır örnekler için örnek kodlar sayfasına bakın. Diğer diller için PHP ve Node.js SDK sayfaları, API'nin genel kapsamı için API ve SDK entegrasyonu sayfası kullanılabilir.