iyzi — iyzico CLI

Terminalden iyzico ödemeleri. Ödeme oluştur/sorgula, iade/iptal, 3DS başlat, webhook doğrula, BIN/taksit sorgula — hepsi tek komutla, makine-okur --json çıktısıyla, çift-tahsilata karşı yerel guardrail'lerle.

Neden bu araç?

• 🔒 Kart verisi sızmaz — PAN/CVC/secret hiçbir log, defter veya hata mesajında görünmez (PCI bilinçli, testle kanıtlı).
• 🔁 Çift tahsilat koruması — iyzico idempotent değildir; yerel defter + mutabakat ile kör retry engellenir.
• 🤖 Agent-dostu — kararlı --json, stabil exit kodları, asla beklenmedik prompt.
• 💯 Doğru para — Decimal ile kuruş hassasiyeti (float sapması yok).

Not: Bu, iyzico'nun resmi ürünü değildir — iyzico API'si üzerine geliştirilmiş bağımsız bir araçtır. iyzi-cli is an unofficial developer tool and is not affiliated with iyzico.

⚠️ Önce sandbox. Tüm geliştirme ve denemeler sandbox ortamında yapılır. Canlıya (production) ancak akış oturduktan sonra geçilir.

60 saniyede başla

# İzole CLI kurulumu için pipx veya uv önerilir:
pipx install iyzi-cli            # veya:  uv tool install iyzi-cli
# (sade pip de olur:)
pip install iyzi-cli

cp .env.example .env             # sandbox anahtarlarınızı girin
iyzi durum                       # bağlantı/anahtar kontrolü
iyzi odeme test --tutar 25.00    # test kartıyla örnek ödeme
iyzi completion install          # TAB ile komut tamamlama (bash/zsh/fish)

Tek seferlik deneme (kurulum yapmadan):

uvx iyzi-cli --help

Kurulum

En hızlı yol (GitHub'dan doğrudan):

pip install git+https://github.com/goktugecertastan-cyber/iyzi-cli.git

Veya depoyu klonlayıp geliştirici modunda kurmak için:

git clone https://github.com/goktugecertastan-cyber/iyzi-cli.git
cd iyzi-cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"   # [dev] testleri de kurar

Kurulumdan sonra iyzi komutu kullanılabilir hale gelir:

iyzi --version
iyzi --help

Anahtar ayarı

Anahtarlar asla koda gömülmez. .env dosyasından okunur:

cp .env.example .env
# .env dosyasını açıp kendi sandbox anahtarlarınızı girin

.env dosyası .gitignore'dadır, commit edilmez.

Sandbox anahtarları: https://sandbox-merchant.iyzipay.com

Tanı logu (sorun bildirimi)

Varsayılan olarak hiçbir log dosyası tutulmaz. Bir hatayı destek ekibine iletmeniz gerekirse, tanı logunu açıkça etkinleştirin:

IYZI_LOG=1 iyzi odeme getir --id 12345678

Bir hata oluşursa kayıt ~/.iyzi/logs/error.log dosyasına (izin 600) yazılır ve CLI size bu yolu gösterir. Log dosyası kart numarası, CVV veya API/secret anahtar İÇERMEZ — yazılan tüm metin diske ulaşmadan maskelenir (PAN → son 4, CVV/secret → gizli). Bu dosyayı güvenle destek ekibimize iletebilirsiniz.

Kullanım

# Adım adım kurulum (ortam + anahtarları sorar, doğrular, .env'e yazar)
iyzi setup

# Ortam/kurulum teşhisi (sürümler, ortam, config kaynağı — sır göstermez)
iyzi doctor

# Anahtar/bağlantı kontrolü
iyzi durum

# Test kartıyla örnek ödeme (sandbox — canlıda çalışmaz)
iyzi odeme test --tutar 25.00

# Gerçek kart bilgisiyle Non-3DS ödeme
# GÜVENLİK: kart no ve CVC'yi bayrakta vermeyin — verilmezse güvenli (gizli)
# olarak sorulur. Böylece shell geçmişine/process listesine sızmazlar.
iyzi odeme olustur --tutar 99.90 --kart-sahibi "John Doe" \
  --son-ay 12 --son-yil 2030
#   → "Kart numarası:" ve "CVC:" gizli sorulur

# (Sandbox otomasyonu için bayraklar yine kullanılabilir — riski göze alarak)
iyzi odeme olustur --tutar 99.90 --kart-sahibi "John Doe" \
  --son-ay 12 --son-yil 2030 --kart-no 5528790000000008 --cvc 123

# 3DS ödeme başlat (doğrulama formu + paymentId döner)
iyzi odeme 3ds-baslat --tutar 99.90 --kart-sahibi "John Doe" \
  --son-ay 12 --son-yil 2030 \
  --callback-url https://siteniz.com/3ds-callback --html-kaydet form.html

# Ödeme detayı getir
iyzi odeme getir --id <PAYMENT_ID>

# İade (onay ister)
iyzi iade yap --tx <TRANSACTION_ID> --tutar 10.00

# Ödeme iptali (onay ister)
iyzi iade iptal --id <PAYMENT_ID>

# Çoklu hesap: isimli profiller (sandbox-dev, production vb.)
iyzi config set sandbox-dev --env sandbox   # anahtarlar gizli sorulur
iyzi config use sandbox-dev
iyzi config list

# BIN sorgulama (kartın bankası/tipi) ve taksit seçenekleri
iyzi bin sorgula --kart-no 552879
iyzi bin taksit --kart-no 552879 --tutar 100.00

# Hata kodu açıklaması (yerel sözlük, API çağrısı yok)
iyzi hata 10051

# Sahte (imzalı) webhook üret — kendi sunucunu test etmek için
iyzi webhook uret --odeme-id 12345 --durum SUCCESS

# Ham API erişimi — özel komutu olmayan her endpoint
echo '{"binNumber":"552879"}' | iyzi api post /payment/bin/check

Webhook imza doğrulama

iyzico, webhook bildirimlerine X-IYZ-SIGNATURE-V3 başlığı ekler. Sunucunda bu imzayı doğrulamadan bildirime güvenmek güvenlik açığıdır. Bu komut imzayı senin yerine doğru üretip karşılaştırır (tamamen yerel, API çağrısı yok):

# Gelen bildirimi (JSON) ve imzayı doğrula:
iyzi webhook dogrula --govde bildirim.json --imza <X-IYZ-SIGNATURE-V3>

# Sunucu logundan pipe ile:
cat bildirim.json | iyzi webhook dogrula --imza <SIGNATURE>

# Hosted Payment Page formatı için:
iyzi webhook dogrula --govde bildirim.json --imza <SIG> --hpp

# Sadece beklenen imzayı üret (test/hata ayıklama):
iyzi webhook dogrula --govde bildirim.json --uret

Geçerli imza → çıkış kodu 0, geçersiz → 1.

3DS hakkında not

3DS ödemeler tarayıcı gerektirir: 3ds-baslat size bir HTML doğrulama formu (threeDSHtmlContent) ve paymentId döndürür. Bu formu kullanıcıya gösterirsiniz, kullanıcı OTP girer, iyzico --callback-url'inize paymentId ile döner. Ödemeyi tamamlamak (Auth-3DS) backend'inizde o paymentId ile yapılır — tarayıcı adımı CLI kapsamı dışındadır.

Testler

pip install -e ".[dev]"

# Birim testler (ağsız, hızlı — entegrasyon otomatik atlanır):
pytest

# Entegrasyon + uçtan uca (gerçek sandbox, anahtar gerekir):
IYZI_ENV=sandbox IYZI_API_KEY=... IYZI_SECRET_KEY=... pytest -m "integration or e2e"

Test katmanları: birim (mock, CI'da her zaman) · integration (sandbox kimlik/bağlantı) · e2e (ödeme→sorgu→iade yaşam döngüsü). Anahtar yoksa entegrasyon/e2e testleri güvenle atlanır.

Girdi doğrulama: tutar, taksit, kart numarası (Luhn), son kullanma tarihi ve CVC, API'ye gönderilmeden önce yerel olarak doğrulanır — hatalı girdi anlaşılır bir mesajla reddedilir, iyzico'ya gereksiz istek gitmez.

Faydalı bayraklar

Her komutta --help çalışır:

iyzi --help
iyzi odeme --help
iyzi iade yap --help

Sekme tamamlama (tab completion)

Komutları ve seçenekleri TAB ile tamamlayın (bash / zsh / fish):

iyzi completion install        # aktif shell'i bulur, başlangıç dosyasına ekler
# veya elle incelemek için:
iyzi completion show zsh       # script'i basar (kurmaz)

Sonra yeni bir terminal açın (veya source ~/.zshrc). Artık iyzi od<TAB> → odeme, --tut<TAB> → --tutar çalışır. Kurulum idempotenttir (iki kez çalıştırmak güvenlidir).

Çıktı kuralları

• Başarı sessiz, hata gürültülü. İnsan mesajları stderr'e, asıl veri stdout'a gider — böylece --json çıktısı pipe ile temiz akar.
• Çıkış kodu (exit code): başarı 0, API/iş hatası 1, kimlik/config hatası 2, kullanıcı iptali (Ctrl+C) 130. Script'lerde güvenle kontrol edilebilir.

AI agent / otomasyon

CLI, AI agent'ları ve otomasyon sistemleri tarafından güvenli kullanılacak şekilde tasarlandı (kararlı JSON, çift-tahsilat guardrail'i, mutabakat):

• Operasyon defteri (IYZI_LEDGER=1): para hareketlerini yerel olarak izler; retry-öncesi "bunu zaten denedim mi?" kontrolü yapar (iyzico idempotent değildir). iyzi ledger list|show|reconcile. Defter kart/CVC/secret saklamaz.
• Mutabakat: iyzi ledger reconcile / iyzi odeme getir ağ hatası sonrası "ödeme oldu mu?" sorusunu deterministik yanıtlar.
• Raporlama: iyzi rapor islem|gunluk (hesapta raporlama servisi etkinse).

Ayrıntılı rehberler:

• docs/agent-reference.md — komut matrisi, exit kodları, güvenli retry, "ağ koptu ne yapmalı" senaryosu.
• docs/json-contracts.md — JSON istek/yanıt şekilleri.
• docs/3ds-lifecycle.md — uçtan uca 3DS akışı.
• docs/webhooks.md — webhook üretim/doğrulama.
• docs/production-runbook.md — üretim geçişi.
• docs/smoke-test.md — uçtan uca smoke test (sandbox + production).

Canlıya geçiş

1. .env içinde IYZI_ENV=production yapın.
2. Gerçek anahtarları girin (https://merchant.iyzipay.com).
3. Canlı ortamda CLI her komutta kırmızı uyarı gösterir.
4. Adım adım güvenli geçiş: docs/production-runbook.md.

Mimari

iyzi/
  config.py      Anahtar/ortam yönetimi (bayrak > env > .env > profil önceliği)
  client.py      API istemcisi + hata yorumlama
  signing.py     IYZWSv2 istek imzalama (kendi uygulamamız)
  validators.py  Girdi doğrulama (tutar, kart/Luhn, tarih, CVC, callback URL)
  errors.py      iyzico hata kodu sözlüğü (yerel)
  webhook.py     Webhook imza üretme/doğrulama (X-IYZ-SIGNATURE-V3)
  profiles.py    İsimli profil yönetimi (XDG, izin 600)
  cli.py         Click komut arayüzü
  output.py      Tablo/JSON/renk çıktı yardımcıları
  samples.py     Sandbox test kartı ve örnek veriler

Kimlik bilgisi önceliği: bayrak > ortam değişkeni > .env > aktif profil.

İmzalama: Standart ödeme/iade akışları resmi iyzipay SDK ile yapılır. Ek olarak signing.py iyzico'nun IYZWSv2 imza protokolünü (HMAC-SHA256 + base64) sıfırdan uygular; api post ham erişim komutu bunu kullanır ve SDK'ya bağımlı değildir. Bu uygulamanın SDK ile birebir aynı imzayı ürettiği testlerle kanıtlanır (tests/test_signing.py).