Elixir SDK

Güncel kaynak sürümü: 0.1.1. Aşağıdaki önceki 0.1.0 kayıt deposu sürümü doğrulanmış yayındır; yeni kaynak yamasının orada yayımlandığı iddia edilmez.

Yeni kaynak yaması mağaza sitesi için somut bir sunum örneği ekler. Varsayılan gömülü ödemedir: yalnız resmi Lunixi bundle yüklenir ve mevcut form mount edilir; yöntem ve çoklu kart seçenekleri Lunixi panelinde kalır. İsteğe bağlı yönlendirme yalnız backend paymentPageUrl adresini, tam HTTPS pay.lunixi.com/payment/ doğrulamasından sonra kullanır. Adresin token’ı gömülü token’dan farklı olabilir. Eksik adres gömülü ödemeyi engellemez; yönlendirme aynı deneme/anahtarla inceleme veya uzlaştırmada kalır. Tarayıcı token’ından adres üretmeyin. Formdan önce müşteri/sipariş sahipliğini ve yerel tarayıcı CSRF’yi doğrulayın; Cache-Control: private, no-store gönderin, mağazanın CSP nonce değerini koruyun; token, HTML ve yönlendirme adreslerini loglamayın. Genel yanıt verisi paymentPageUrl alanını korur; yeni tipli ürün eşitliği iddiası yoktur.

:lunixi, Elixir 1.20+ ve Erlang/OTP 29+ sunucu SDK'sıdır. Phoenix, Plug, LiveView sunucu süreçleri ve OTP uygulamalarında kullanılır. OTP Ed25519/HMAC, Req sertifika doğrulamalı HTTPS sağlar.

Hex üzerinden kurulum

Lunixi 0.1.0, Hex.pm’de son doğrulanan sürümdür (opens in a new tab). Bu eski registry seçeneği, güncel 0.1.1 sunum örneğinden ayrıdır; burada Hex.pm 0.1.1’in erişilebilir olduğu iddia edilmez. Önceki sürümü mix.exs dosyanızda sabitlemek için:

{:lunixi, "0.1.0"}

Ardından mix deps.get çalıştırın.

Güncel gömülü/yönlendirmeli örnek için eski Hex bağımlılığı yerine yayımlanmış v0.1.1 kaynak etiketini kullanın:

{:lunixi, git: "https://github.com/Lunixi-Payment/lunixi-elixir.git", tag: "v0.1.1"}

v0.1.1 kaynak kodu ve örnekleri (opens in a new tab). Çözümlenen kaynak commit’ini korumak için mix.lock dosyasını saklayın. Sunum örneğini kimlik korumalı mağaza uygulamanıza uyarlayın; kendiliğinden herkese açık ödeme rotası kurulmaz.

İsteğe bağlı SQLite inbox için ayrıca {:exqlite, "~> 0.43.0"} ekleyin. Hazır NIF yoksa C derleyicisi gerekir. Ödeme/imza/webhook doğrulaması veritabanı sürücüsü istemez.

Merchant başına supervised istemci

config = %Lunixi.Config{
  base_url: "https://api-gateway.lunixi.com",
  key_id: System.fetch_env!("LUNIXI_KEY_ID"),
  private_key: System.fetch_env!("LUNIXI_PRIVATE_KEY_PEM"),
  max_retries: 2
}
children = [{Lunixi.Client, name: MyApp.Lunixi, config: config}]
Supervisor.start_link(children, strategy: :one_for_one)

Ed25519 açık anahtarını panelde kaydedin; özel anahtar sunucuda kalır. PKCS8 PEM, base64 PKCS8 DER, base64 32 bayt seed ve doğrulanmış base64 64 bayt keypair desteklenir. TEST/LIVE ortamını anahtar seçer. Secret tarayıcıya gönderilmez.

Her istemci bir merchant anahtarı/önbellek taşır. Birden fazla merchant için ayrı kayıtlı ad/Registry kullanın. Token ihtiyaç anında alınır; eşzamanlı edinim birleştirilir ve süre dolmadan yenilenir. İmza/token istemcide sıralanır; ödeme HTTP çağrıları çağıran süreçlerde eşzamanlı yürür. Supervised yeniden başlatmada token tekrar alınır, diske yazılmaz.

Yapılandırma/yanıt Inspect ve JSON çıktısı secret/gövdeyi, OTP süreç durumu state/mesajı gizler. Ham map, açık veri erişimcileri ve süreç izleme yine hassastır; loglanmaz ve güvenilmeyen kişilere açılmaz. BEAM belleği sıfırlama garantisi vermez.

BaseURL yol, kullanıcı bilgisi veya sorgu içermeyen güvenilir HTTPS kökenidir. Yönlendirmeler ve Req tekrarları kapalıdır. Sertifika/host doğrulaması açık kalır. Auth/tekrar içeren iş akışının tamamına uygulama düzeyinde deadline koyun.

Checkout başlatma

Toplam/sepeti sunucu kayıtlarınızdan alın. Anahtarı API çağrısından önce kaydedin; belirsiz sonucu aynı gövde/anahtarla tekrar edin.

alias Lunixi.Payment.{Intent, BasketItem}
intent = %Intent{
  amount: 10050, currency: "TRY", order_id: "ORD-1001",
  callback_url: "https://merchant.example/payment/return",
  basket_items: [
    %BasketItem{id: "line-1", name: "Örnek ürün", item_type: "PHYSICAL", price: 10050}
  ]
}
with {:ok, response} <- Lunixi.Payments.create_intent(MyApp.Lunixi, intent, kayitli_deneme_anahtari),
     %{"token" => token} when is_binary(token) and token != "" <- response.data do
  Lunixi.CheckoutHTML.render(token, nonce: sunucu_csp_nonce)
end

HTML/token dönmeden önce müşterinin sipariş yetkisini doğrulayın, Cache-Control: no-store kullanın. CheckoutHTML yalnız resmî https://cdn.lunixi.com/lunixi-checkout.min.js dosyasını yükler; token JSON'unu HTML için kaçırır, CSP nonce'ını doğrular ve mevcut Lunixi formunu açar. Özel script URL'si üretmeyin veya rastgele dönen HTML'i basmayın. Form açık kart/alternatif yöntemleri gösterir; varsayılan örnekler PAN/CVV toplamaz.

Tutar pozitif tam sayı kuruştur; en fazla 9007199254740991 kabul edilir. 10050 = 100,50 TRY. Sepet price kalem toplamıdır; toplam kök amount ile eşleşir. Kök ödeme tutarı tek alandır. Taksit/vade farkını form yönetir. Alıcı/adres ve belgelenmiş sigorta sepeti string anahtarlı şemalardır. preauth/force_3d açık false değerini korur. Yöntem kısıtlaması yalnız panelde açık yöntemleri daraltır.

Token, tarayıcı tamamlanması, HTTP başarısı veya AUTHORIZED tahsilat kanıtı değildir. Gateway sonucunu doğrulayıp merchant/sipariş/ödeme kimliği, beklenen tutar/para birimi ve nihai tahsilat/uzlaştırmayı eşleştirmeden teslimat yapmayın. İade, iptal ve itiraz ayrı geçişlerdir.

API kapsamı

Lunixi.Payments.refund(MyApp.Lunixi, payment_id, 2500, "Müşteri iadesi", kayitli_iade_anahtari)

nil tutar tam capture/refund ister. void provizyonu bırakır. Split tam sayı tutarları, 1–5 bacağı ve eşit toplamı denetler; yönteme özgü şema gateway'de doğrulanır. Bekleyen split HTTP 400 içeren yanıt dönebilir ve ödenmiş sayılmaz. Telafi, kısmi iade ve uzlaştırma ayrı işlenir.

Yanıt envelope, data, page_info, içerik tipi, request ID ve ikili bytes korur. JSON tutarları tam sayı kalır. Hata yalnız güvenli tür/kod/durum/request ID taşır; uzak gövde/mesaj/URL veya secret yoktur. Açık yanıt verisi yine müşteri bilgisi içerebilir ve loglanmamalıdır.

0.1.0 sürümünde cüzdan, banka, ödeme linki, sigorta, pazaryeri, abonelik veya kimlik için ayrı tipli modüller yoktur. REST şemalarını genel taşıma üzerinden kullanın; tipli yardımcı eşitliği iddia edilmez.

Lunixi.request(MyApp.Lunixi, :get, "/api/v1/payments", query: [{"limit", "20"}])

Kanonik JSON JavaScript sayısal anahtar sırası, sıkıştırılmış UTF-8 ve kısa sayı biçimini izler. Yinelenen anahtarlar, aşırı iç içelik ve güvensiz tam sayılar ağdan önce reddedilir. Sorgu ayrı kodlanıp imzaya girer. Auth isteği gövde/Digest taşımaz.

Bilinen ödeme mutasyonları kayıtlı 16–128 karakterlik boşluksuz yazdırılabilir ASCII anahtar ister. Tekrar aynı anahtar/gövde ve yeni nonce ile gider. Yalnız GET/anahtarlı istekler yapılandırılan sınırda tekrarlanır; anahtarsız mutasyon kör tekrarlanmaz. Belirsiz sonucu yeni denemeden önce uzlaştırın.

Webhook ve kalıcı tekrar koruması

{:ok, event} = Lunixi.Webhook.verify(ham_govde, baslik_ciftleri,
  secrets: [System.fetch_env!("LUNIXI_WEBHOOK_SECRET")])

Boyutu sınırlı ham baytları JSON middleware'den önce alın. Yinelenen başlıkları birleştirmeden çift listesi verin. OTP HMAC/hash_equals event ID, zaman damgasının birebir metni ve ham baytları sabit zamanda doğrular. Varsayılan tolerans 5 dakika; aralık 1–900 saniyedir ve kapatılamaz. now güvenilir test saatidir, istemci zamanı değildir. İmzalı gövdede type gerekir; başlık/JSON tekrarları ve ID/tür uyuşmazlığı reddedilir. En fazla üç güncel/önceki secret rotasyon sağlar.

Doğrulama olay kaydı oluşturmaz. Exqlite kuruluyken:

:ok = Lunixi.SqliteInbox.ensure_schema(connection) # başlangıç/migration
{:ok, uygulandi} = Lunixi.SqliteInbox.process(connection, merchant_scope, event, fn transaction ->
  dogrulanmis_siparisi_isle(transaction, event)
end)

dogrulanmis_siparisi_isle, finansal alanları eşleyip aynı bağlantıda sipariş/outbox güncelleyen adaptörünüzdür. Bağlantı transaction boyunca tek sürecin olmalı; bağımsız süreçler ayrı bağlantı açmalıdır. Native busy timeout kısa tutulur (örnek 100 ms); kilit/depolama hatasına yeniden teslimi sağlayan HTTP hatası dönülür.

Marker ve iş durumu birlikte commit edilir. Tekrar callback'i çalıştırmaz; aynı ID farklı gövdeyle gelirse reddedilir. Callback/commit/depolama hatası marker'ı geri alır. Merchant scope ayırın, kayıtları replay politikanız boyunca tutun, harici yan etkileri outbox'a yazın. Depolama hatasına 2xx dönmeyin. Başka veritabanında aynı unique-event/hash + iş güncellemesi transaction sözleşmesi gerekir. Yalnız doğrulayıcının döndürdüğü olayları işleyin.

Kalıcı bildirim örneği (opens in a new tab), gerçek stdin/başlık teslimini doğrulayıp yalnız ID/tür kaydeder; siparişi tamamlamaz. TEST checkout örneği (opens in a new tab) token'ı çıktıya basmaz. Eski olay için zamanı atlamak yerine yeni sağlayıcı replay'i isteyin.

Doğrulama

mix deps.get --check-locked
mix format --check-formatted
mix compile --warnings-as-errors
mix test
mix credo --strict --only warning
mix deps.audit
mix hex.audit
mix hex.build

Testler gerçek yerel TLS ve sentetik CA (OpenSSL CLI), bağımsız Node.js JSON/Ed25519/HMAC vektörleri, eşzamanlı token, kötü niyetli form girdisi ve SQLite geri alma/yeniden başlatma/tekrar içerir. Anahtarlar sentetiktir; canlı merchant çağrısı yapılmaz. Credo uyarı/güvenlik kontrolleri çalışır; Dialyzer kanıtı iddia edilmez. Güvenlik politikası (opens in a new tab).

Mağaza içi entegrasyon örneği

Kaynak CheckoutPresentation adaptörü (opens in a new tab), mevcut Lunixi.CheckoutHTML.render/2 yöntemini çağırır. present(response.data, nonce: nonce) varsayılan olarak {:ok, {:html, fragment}}; açık mode: :hosted ise yalnız doğrulanmış {:ok, {:redirect, url}} döndürür. Örneği kendi yetkili mağaza controller’ınızda yükleyip yerel CSRF ve no-store denetimini uygulayın. Mevcut yanıt zaten paymentPageUrl alanını korur; tarayıcı ve yönlendirme token’ları bağımsızdır.