Payment Orchestrator
Payment Orchestrator, birden fazla ödeme sağlayıcısı üzerinden ödeme almak ve yönetmek için tek bir API'dir. Bir kez entegre olursunuz; Lunixi her işlemi optimal sağlayıcıya yönlendirir, 3D Secure'ü yönetir, kurtarılabilir hataları alternatif sağlayıcıda yeniden dener ve her durum değişikliğini tutarlı bir status modeli ve webhook'larla size raporlar.
API genelinde tüm tutarlar minor-unit (kuruş) cinsinden tam sayıdır. "amount": 10050 = ₺100,50 demektir. Hiçbir yerde ondalıklı tutar yoktur.
Üç ürün hattı
Payment Orchestrator sekmesi; aynı platformu, aynı kimlik doğrulama modelini ve aynı webhook teslimatını paylaşan üç ürün hattını kapsar:
| Hat | Ne yapar | Buradan başlayın |
|---|---|---|
| Ödeme | Tek seferlik kart ödemeleri — hosted checkout formu, direct API veya paylaşılabilir ödeme linki, 3D Secure, taksit, capture/void/refund, ters ibraz | Hızlı Başlangıç · Linkle Ödeme |
| Pazaryeri | Tek bir çekimi alt satıcılara böler, satıcı onboarding'i, komisyon ve payout yönetimi | Pazaryeri genel bakış |
| Subscription | Tekrarlayan faturalama — ürünler, planlar, faturalar, kayıtlı kartlar, kullanım ölçümü ve hazır müşteri portalı | Subscription genel bakış |
Kendi markanız altında cüzdan işletmek — bakiye yükleme, cüzdandan cüzdana transfer, cüzdanla ödeme, QR ve sadakat — ayrı bir üründür: Cüzdan. Kart ödemesini karta değil cüzdana iade etmek için Cüzdana İade sayfasına bakın.
Ödeme almanın iki yolu
| Hosted checkout | Direct API | |
|---|---|---|
| Kart verisi | Lunixi'nin checkout formunda girilir — kart verisi sunucunuza hiç uğramaz | Backend'inizden sunucudan sunucuya gönderilir |
| Çağıracağınız | POST /payments/intents, sonra dönen token ile formu mount edersiniz | POST /payments/direct/payment (Payment) |
| PCI kapsamı | Minimum — kartı Lunixi işler | Tam — sizin tarafınızda PCI DSS uyumluluğu gerektirir |
| Kimin için | En hızlı, en düşük uyumluluk yüklü entegrasyon | Ödeme deneyimi üzerinde tam kontrol |
İki yol da aynı sağlayıcı yönlendirmesini, failover'ı, 3D Secure yönetimini, taksit mantığını ve webhook'ları paylaşır. Entegrasyonların çoğu hosted checkout ile başlamalıdır — eksiksiz referans için Checkout Formu sayfasına bakın.
Sitenizde ödeme formu olmadan ödeme almak için Linkle Ödeme'yi kullanın: API ile bir link oluşturursunuz, alıcı ödemeyi pay.lunixi.com üzerinde, aynı Lunixi ödeme formuyla yapar.
Çoklu sağlayıcı yönlendirme & failover
Hesabınıza birden fazla ödeme sağlayıcısı (ve sağlayıcı başına birden fazla credential) bağlayabilirsiniz. Lunixi'nin akıllı yönlendirmesi her işlem için o ödemeye özel optimal sağlayıcıyı seçer — anlık sağlayıcı sağlığını, geçmiş performansı ve maliyeti dikkate alır; sizin tarafınızda yönlendirme kodu gerekmez.
Bir ödeme başarısız olduğunda önce hata sınıflandırılır:
- Yeniden denenebilir hatalar (sağlayıcı kesintisi, ağ zaman aşımı, rate limit) otomatik olarak sıradaki uygun sağlayıcıya yönlendirilir — alıcı genellikle fark etmez.
- Yeniden denenemez retler (yetersiz bakiye, geçersiz kart, başarısız 3D Secure) nihai olarak döner. Bunları başka sağlayıcıda tekrar denemek alıcının vaktini harcar ve fraud alarmlarını tetikleyebilir; orkestratör bunu asla yapmaz.
Takip işlemleri — capture, void, refund — her zaman ödemeyi işleyen orijinal sağlayıcı ve credential üzerinden yapılır. Asla yeniden yönlendirilmez.
Ödeme yaşam döngüsü
Her ödeme açık bir status üzerinden ilerler. GET /payments/:id yanıtında ve webhook payload'larında göreceğiniz değerler birebir şunlardır:
CAPTURED ile alınır, AUTHORIZED ile değil — otorizasyon yalnız bloke koyar. Terminal/istisnai durumlar (FAILED, EXPIRED, CHARGEDBACK, NEEDS_RECONCILIATION) aşağıdaki tabloda.| Status | Anlamı |
|---|---|
INITIATED | Intent oluşturuldu, henüz çekim denemesi yok |
PROCESSING | Bir çekim denemesi sürüyor |
AWAITING_3D | Alıcı 3D Secure doğrulamasına yönlendirildi |
AUTHORIZED | Tutar bloke edildi, henüz capture edilmedi |
CAPTURED / PARTIALLY_CAPTURED | Tutar (tamamen veya kısmen) capture edildi |
SETTLED | Tutar sağlayıcı tarafında mutabakata girdi |
REFUNDED / PARTIALLY_REFUNDED | İade yapıldı (tamamen veya kısmen) |
VOIDED | Otorizasyon capture öncesi serbest bırakıldı |
FAILED | Nihai ret |
EXPIRED | Terk edilen checkout veya 3D Secure oturumu otomatik kapatıldı |
CHARGEDBACK | Ters ibraz açıldı — bkz. Ters İbraz |
NEEDS_RECONCILIATION | Sonuç belirsiz; sessizce FAILED yapılmak yerine incelemeye alındı |
Güvenlik modeli
- Okuma endpointleri (listeleme, ödeme detayı, BIN sorguları) sunucu tarafı Bearer erişim token'ı (
at_live_…) kullanır. - Para hareketi endpointleri (intent oluşturma, direct çekim, capture/void/refund) Step-Up auth ister: Bearer key artı Ed25519 istek imzası.
- Hosted formun alıcı tarafı, kısa ömürlü form token ve session-proof cookie ile doğrulanır — secret key'iniz tarayıcıya asla gitmez.
- Her ödeme POST'u
Idempotency-Keyheader'ı kabul eder; böylece bir ağ tekrarı asla çift çekime dönüşemez.
Modelin tamamı, imzalama örnekleriyle birlikte Kimlik Doğrulama sayfasındadır.
Webhook'lar
Ödeme durum değişiklikleri, imzalı webhook eventleri olarak endpoint'inize iletilir:
payment.authorized · payment.captured · payment.partially_captured · payment.failed · payment.refunded · payment.partially_refunded · payment.voided · payment.expired · payment.disputed
Ödeme sonuçları için gerçeğin kaynağı olarak webhook'ları kullanın; durumu anlık teyit etmek için GET /payments/:id çağırın — bkz. Webhook'lar.