lunixi-sdk 0.1.2

data/docs/rails.tr.md

@@ -0,0 +1,112 @@
+---
+title: Rails
+description: Lunixi Ruby SDK için çalıştırılabilir Rails örneği — hosted ödeme, şifreli token, CSRF, kalıcı webhook dedupe ve ödeme mutabakatı.
+---
+
+
+# Rails
+
+[Ruby SDK](/sdks/ruby) kaynak deposundaki `samples/rails`, çalıştırılabilir Rails 8.1 referans uygulamasıdır. Sunucuda hesaplanan tutarla hosted ödeme başlatır; token’ı şifreli saklar, alıcı rotalarını CSRF ve demo kimlik doğrulamayla korur, doğrulanmış webhook receipt’i ile sipariş değişikliğini atomik commit eder.
+
+Örnek **tek üye işyeri ve sabit toplamlı TRY siparişleri** içindir. Ayrı yayımlanmış Rails gem’i veya tamamlanmış mağaza değildir. İmza, token önbelleği, retry ve webhook kriptografisi `lunixi-sdk` içinde kalır.
+
+## Kurulum
+
+Ruby 3.3+, Bundler, Ed25519 destekli OpenSSL ve SQLite gerekir. SDK’nın bağımsız JSON uyum testi Node.js kullanır.
+
+```bash
+git clone https://github.com/Lunixi-Payment/lunixi-ruby.git
+cd lunixi-ruby
+bundle install
+```
+
+Gemfile, yerel SDK ile Rails, Puma ve SQLite bağımlılıklarını kurar. `lunixi-sdk` için RubyGems yayını varsayılmaz. [Örnek kaynak kod](https://github.com/Lunixi-Payment/lunixi-ruby/tree/main/samples/rails).
+
+## Secret ayarları
+
+Başlamadan önce değişkenleri shell veya secret manager üzerinden dışa aktarın. Uygulama dotenv’i otomatik yüklemez; depodaki `samples/rails/.env.example` kontrol listesi olarak kullanılabilir.
+
+| Değişken | Amaç |
+| --- | --- |
+| `LUNIXI_BASE_URL` | HTTPS gateway origin; normalde `https://api-gateway.lunixi.com` |
+| `LUNIXI_KEY_ID` | Kayıtlı TEST/LIVE üye işyeri key id |
+| `LUNIXI_MERCHANT_ID` | Doğrulanmış ödeme yanıtıyla birebir eşleşmesi gereken üye işyeri UUID değeri |
+| `LUNIXI_PRIVATE_KEY_PATH` | Public web dizini dışındaki özel Ed25519 anahtarı |
+| `LUNIXI_WEBHOOK_SECRET` | Kayıtlı webhook bağlantısına ait secret |
+| `PUBLIC_ORIGIN` | Bu Rails uygulamasının public HTTPS origin’i; path içermez |
+| `DEMO_USERNAME`, `DEMO_PASSWORD` | Demo HTTP Basic; parola en az 16 bayt |
+| `SECRET_KEY_BASE` | Kalıcı Rails session secret |
+| `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY` | Kalıcı ana şifreleme anahtarı |
+| `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` | Bağımsız deterministik şifreleme anahtarı |
+| `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` | Bağımsız türetme salt’ı |
+
+Session secret için yerelde `ruby -rsecurerandom -e 'puts SecureRandom.hex(64)'` çalıştırın. Şifreleme ayarları için üç bağımsız, rastgele 32 bayt değer daha üretin. Güvenle saklayın ve yeniden başlatmada koruyun. Rails anahtar rotasyonunu planlamadan anahtarları değiştirmeyin; eski anahtarı kaybetmek kayıtlı token’ları okunamaz yapar.
+
+Yerel HTTPS tüneli `PUBLIC_ORIGIN` sağlayabilir. Bu origin dönüş URL’si ve izin verilen host için kullanılır; uygulamadan önce ayarlanmalıdır. Geliştirme sunucusunu kimlik doğrulama olmadan public açmayın.
+
+## Ödeme başlatma
+
+```bash
+cd samples/rails
+bundle exec rails db:migrate db:seed
+bundle exec rails server -b 127.0.0.1
+```
+
+`http://localhost:3000/orders/00000000-0000-4000-8000-000000000001` adresini açın, demo bilgileriyle giriş yapıp ödeme butonuna basın. Sentetik başlangıç siparişi **100,50 TRY**’dir. Türkçe arayüz için `?locale=tr` ekleyin.
+
+Checkout POST’u CSRF token ister; tutar/para birimini veritabanından okur. Gateway çağrısından önce siparişe UUID `checkout_key` kaydedilir. Aynı anahtarla intent oluşturulur, `intent_id` saklanır ve `checkout_token` Active Record Encryption ile şifrelenir. Ardından sabit `pay.lunixi.com` host’una 303 yönlendirmesi yapılır. Yeni ve kayıtlı token’lar ASCII allowlist ile doğrulanır; tarayıcı veya gateway başka host/protokol veremez.
+
+Ağ hatasında sipariş pending kalır, işlem anahtarı korunur. Checkout tekrarında aynı anahtar kullanılır. Kayıtlı token yeniden kullanılır; belirsiz deneme silinip sessizce yeni tahsilat açılmaz. Süresi dolmuş veya sonucu bilinmeyen deneme mutabakat gerektirir.
+
+Lunixi formu, üye işyerine açık yöntemleri ve uygun alternatif/çoklu kart akışlarını sunar. Uygulama PAN/CVV işlemez.
+
+## Webhook kaydı
+
+Lunixi panelinde aşağıdaki URL’yi kaydedip eşleşen webhook secret’ını ayarlayın:
+
+```text
+https://<public-hostunuz>/webhooks/lunixi
+```
+
+Dokümante ödeme olaylarına abone olun. Dış çağrı alan `WebhooksController < ActionController::API`, özgün `request.raw_post` baytlarını kullanır ve tarayıcı session’ına bağlı değildir. Ayrı middleware yalnız `POST /orders/{public_id}/return` bilgi dönüşünü de kabul eder: atılan ham gövdeyi 1 MiB ile sınırlar, bütün alanları yok sayar; sipariş/oturum sorgusu, gateway çağrısı veya mali yazım yapmadan mevcut kimlik doğrulamalı GET adresine boş ve sabit aynı-origin 303 verir. Bu bilgi adaptörü webhook sırrını kullanmaz. Checkout CSRF ve kimlik doğrulamayı korur. Normal GET deneme kimliğini ister; yayında gerçek müşteri/sipariş yetkisine bağlanmalıdır.
+
+SDK v2 imza, zaman, olay kimliği/tipi ve rotasyonu doğrular. `RailsReplayStore`, benzersiz `(connection_id, event_id)` constraint’i olan receipt’i sipariş değişikliğiyle **aynı veritabanı transaction’ına** yazar. Aynı olay ikinci kez 200 döner ve sipariş yeniden işlenmez. Aynı kimliğin farklı baytları 400 alır. İşleyici veya sunucu ödeme sorgusu hatası receipt’i geri alır ve 503 döndürür; tekrar teslim kurtarabilir.
+
+## Tahsilat doğrulama
+
+`WebhookProcessor`, `payment.captured` olayını yalnız kayıtlı sipariş/intent ile eşleştirir. Yetkili `payments.get(intent_id)` çağrısında şunları arar:
+
+- nihai durum `CAPTURED`;
+- aynı kalıcı sipariş referansı ve intent;
+- aynı para birimi;
+- siparişin tam sayı tutarıyla birebir eşleşme.
+
+Bu koşullarla sipariş `paid` olur. Başarısız, yalnız provizyon alınmış, bilinmeyen veya tutarsız sonuç pending kalır. Diğer abone olunan olaylar tahsilat varsayılmadan kaydedilir. Tarayıcı dönüşü yalnız kayıtlı sipariş sayfasına gider; istemcinin `status` / `paid` parametreleri dikkate alınmaz.
+
+> 
+SDK split, capture ve iade çağrılarını destekler. Bu örnek sabit toplamlı tek-intent TRY siparişi tamamlar. Split toplam tahsilat, kısmi teslim, müşteriye yansıtılan sigorta ve ek ücret açmadan önce açık muhasebe/mutabakat mantığı ekleyin. Eşleşmeyen tutar güvenli biçimde pending kalır.
+
+
+## Kendi uygulamanıza uyarlama
+
+Demo HTTP Basic yerine müşteri/session/tenant ve sipariş sahipliği kontrollerinizi bağlayın. Sunucu toplamını, işlem başına kalıcı anahtarı ve atomik receipt/sipariş transaction’ını koruyun. Eksik webhook ve belirsiz sonuçlar için kalıcı mutabakat işi ekleyin; aynı korelasyon verisini kullanın.
+
+Örnek SQLite ile test edilir. Başka üretim veritabanında ilgili Rails adapter’ını kurup transaction/eşzamanlılık kontrollerini yineleyin. Transaction içindeki uzun gateway sorgusu örneği sade tutar ama kapasiteyi sınırlar. Üretimde outbox/state machine ile kısa transaction kullanılabilir; olay kaydı ve iş değişikliğinin atomikliği korunmalıdır.
+
+Yerel/test dışındaki ortamlarda HTTPS zorunludur. Rails yönlendirme adresine checkout token’ını yazabildiği için info istek logları kapalıdır. Ham ödeme/webhook gövdesi veya secret loglamayın. Kalıcı session/şifreleme anahtarları ve kalıcı veritabanı kullanın.
+
+## Test ve güvenlik
+
+Depo kökünde:
+
+```bash
+bundle exec rake test rails:test
+bundle exec rubocop
+bundle exec bundle-audit check --update
+bundle exec brakeman --force --rails8 --path samples/rails --no-pager
+gem build lunixi-sdk.gemspec
+```
+
+Rails testleri sentetik gateway yanıtları ve gerçek SQLite kullanır; anahtar veya para hareketi gerektirmez. Kimlik doğrulama/CSRF, şifreli token, kalıcı anahtar, yönlendirme saldırısı, tarayıcı dönüşüne güvenmeme, imza, dedupe, yanlış tutar/sipariş ve rollback/yeniden teslim kapsanır. Brakeman’ın sabit host yönlendirmesine ait tek düşük güvenli false positive’i, kesin fingerprint ve saldırı testleriyle `samples/rails/config/brakeman.ignore` içinde gerekçelendirilmiştir. Genel bir güvenlik kategorisi kapatılmaz.
+
+Canlıya geçmeden yetkili TEST üye işyeriyle uçtan uca ödeme, webhook ve iade kabul testi yapın. [Örnek README](https://github.com/Lunixi-Payment/lunixi-ruby/tree/main/samples/rails) ve [güvenlik politikası](https://github.com/Lunixi-Payment/lunixi-ruby/blob/main/SECURITY.md).

data/docs/ruby.en.md

@@ -0,0 +1,145 @@
+---
+title: Ruby SDK
+description: Lunixi Ruby SDK — source installation, Ed25519 signing, payments, fraud, durable idempotency and raw-body v2 webhooks.
+---
+
+
+# Ruby SDK
+
+`lunixi-sdk` is a server-side Ruby client for Lunixi. It handles OpenSSL Ed25519 request signing, synchronized token caching, compact JavaScript-compatible JSON, safe retries and raw-body webhook verification. It works with Rails, Sinatra, Rack and plain Ruby. The core gem has no framework dependency; the executable [Rails integration](/sdks/rails) is included in the source repository.
+
+## Requirements and source installation
+
+Ruby **3.3+**, Bundler and an OpenSSL build supporting **Ed25519** are required. The Rails example uses Rails 8.1.
+
+> 
+Version 0.1.1 is distributed from source. RubyGems publication is a separate release step; a registry install is not assumed here.
+
+
+```bash
+git clone https://github.com/Lunixi-Payment/lunixi-ruby.git
+cd lunixi-ruby
+bundle install
+gem build lunixi-sdk.gemspec
+gem install ./lunixi-sdk-0.1.1.gem
+```
+
+Source: [Lunixi-Payment/lunixi-ruby](https://github.com/Lunixi-Payment/lunixi-ruby). An application may also use a reviewed local checkout with `gem 'lunixi-sdk', path: '/absolute/path/to/lunixi-ruby'`. Pin an audited commit if you use a Bundler Git source.
+
+## Client and keys
+
+```ruby
+require 'lunixi'
+
+lunixi = Lunixi::Client.new(
+  base_url: ENV.fetch('LUNIXI_BASE_URL'),
+  key_id: ENV.fetch('LUNIXI_KEY_ID'),
+  private_key: File.read(ENV.fetch('LUNIXI_PRIVATE_KEY_PATH')),
+  timeout: 30,
+  max_retries: 2
+)
+```
+
+`base_url` must be an HTTPS origin such as `https://api-gateway.lunixi.com`, without credentials, a path, query or fragment. The key determines TEST/LIVE behavior. Create one client per merchant connection and reuse it across requests; the token cache is thread-safe.
+
+Generate an Ed25519 key on your server:
+
+```bash
+umask 077
+openssl genpkey -algorithm ED25519 -out lunixi-private.pem
+openssl pkey -in lunixi-private.pem -pubout -out lunixi-public.pem
+```
+
+Register the public key in the Lunixi dashboard and use the resulting key id. Keep the private key outside source control and the public web root. Supported private-key encodings are PKCS#8 PEM, base64 PKCS#8 DER, or a base64 32-byte seed / 64-byte secret. See [Authentication](/getting-started/authentication).
+
+## Payment intent
+
+Persist the payment attempt and its UUID idempotency key before the first request. Calculate prices on your server, not from a browser total.
+
+```ruby
+result = lunixi.payments.create_intent(
+  {
+    amount: 10_050,
+    currency: 'TRY',
+    orderId: order.public_id,
+    callbackUrl: 'https://merchant.example/payments/return',
+    basketItems: [{ id: 'item-1', name: 'Product', itemType: 'PHYSICAL', price: 10_050 }]
+  },
+  idempotency_key: order.persisted_payment_attempt_key
+)
+
+intent_id = result.fetch('data').fetch('paymentId')
+checkout_token = result.fetch('data').fetch('token')
+```
+
+`10_050` means 100.50 TRY in kuruş. Persist the returned intent and encrypt the checkout token at rest. The Rails sample validates the token and builds the fixed-origin hosted checkout address `https://pay.lunixi.com/payment/<token>`. The hosted form shows methods enabled for that merchant, including eligible alternative methods and multi-card flows; availability depends on account configuration. Do not collect PAN/CVV with this SDK.
+
+> 
+An intent/token, HTTP 2xx, return URL or intermediate split state does not prove capture. Correlate a verified webhook with the persisted order and authenticate a payment status read; confirm final status, amount and currency before fulfillment.
+
+
+Amounts must be positive integers within JavaScript's safe integer range. Root `price` and `paidPrice` are rejected even when null. Basket prices and split leg amounts must equal the relevant total. Intent `installment` is rejected because installments are selected in the checkout form. `preauth: true` requests authorization; capture is a separate operation.
+
+## Available helpers
+
+| Operation | API |
+| --- | --- |
+| Create an intent | `lunixi.payments.create_intent(body, idempotency_key:)` |
+| Read/list payments | `lunixi.payments.get(id)`, `lunixi.payments.list(**filters)` |
+| Merchant methods | `lunixi.payments.methods(payment_method: nil)` |
+| Capture | `lunixi.payments.capture(id, idempotency_key:, amount: nil)` |
+| Full/partial refund | `lunixi.payments.refund(id, idempotency_key:, amount: nil, reason: nil)` |
+| Void | `lunixi.payments.void(id, idempotency_key:)` |
+| Split payment | `lunixi.payments.split(body, idempotency_key:)` |
+| Split status/refund | `lunixi.payments.get_split(id)`, `lunixi.payments.refund_split(id, amount:, idempotency_key:, reason: nil)` |
+| Fraud | `lunixi.fraud.evaluate(body)`, `lunixi.fraud.record_event(body, idempotency_key:)` |
+| Advanced signed HTTP | `lunixi.request(method, path, body: nil, query: {}, idempotency_key: nil, signed: true, binary: false)` |
+
+Capture/refund `amount: nil` asks the gateway to use the remaining amount. False, zero, string and fractional amounts are rejected. Persist a separate operation key for each capture, refund or void. Running split HTTP 400 protocol responses are returned only for documented running states; they remain pending, not paid. Response envelopes are preserved.
+
+The advanced transport supports other **documented** gateway routes without a second HTTP implementation:
+
+```ruby
+links = lunixi.request('GET', '/api/v1/payments/links', query: { limit: 20 })
+```
+
+Payment, fraud and webhooks have explicit helpers. Other services require their published REST schema; this version does not provide a separate typed client for every product.
+
+## Webhooks
+
+Get the exact raw request bytes before parsing JSON. Pass the Lunixi signature headers as strings:
+
+```ruby
+verifier = Lunixi::WebhookVerifier.new(
+  secret: ENV.fetch('LUNIXI_WEBHOOK_SECRET'),
+  previous_secrets: []
+)
+
+verifier.process(raw_request_bytes, signature_headers, store: durable_transactional_store) do |event|
+  # Reconcile event.data with the persisted intent/order and payment status.
+  # Commit the business change in the same transaction as the event receipt.
+end
+```
+
+The verifier requires v2 HMAC-SHA256 over `eventId.timestamp.rawBody`, uses constant-time comparison, checks signed id/type consistency, rejects duplicate JSON keys, and accepts timestamps within **300 seconds** by default, including future skew. Up to two previous secrets support rotation. Header names are case-insensitive; duplicate headers are rejected.
+
+Verification alone does not record receipt. Your store implements `process_once(id:, digest:) { … }`: insert a unique event receipt and update the order in one database transaction, return `:processed` / `:duplicate`, and raise `Lunixi::ReplayConflict` for the same id with different bytes. Handler failure must roll back the receipt, allowing redelivery. Retain receipts across process restarts. The Rails example includes a real database store and unique `(connection_id, event_id)` index.
+
+## Errors and retries
+
+`Lunixi::Error` is the base class. `ConfigurationError`, `SignatureError`, `TransportError`, `RedirectError`, `WebhookError` / `ReplayConflict`, and `ApiError` subclasses distinguish failure types. API errors expose `status`, safe `code` / `request_id`, and optional `retry_after`; remote payloads and error text are omitted.
+
+GET/HEAD and idempotency-keyed mutations may retry network errors or HTTP 429/502/503/504, default two retries and maximum three. Retries preserve the body and key while refreshing the nonce/signature. A safe 401 refreshes the token once. Unkeyed mutations are not retried. An uncertain timeout requires reconciliation with the **original** key, never a new charge key.
+
+TLS peer/hostname verification is mandatory; redirects and path/credential injection are rejected. The request limit is 1 MiB; response limit is 8 MiB. `transport:`, `clock:` and `sleeper:` can be injected for deterministic testing. A custom transport returns `Lunixi::Response.new(status:, headers:, body:)` and must preserve TLS, redirect and thread-safety guarantees. `ca_file:` accepts an explicit trust bundle without disabling verification. Ambient proxy credentials are not inherited.
+
+## Testing and Rails
+
+```bash
+bundle exec rake test rails:test
+bundle exec rubocop
+bundle exec bundle-audit check --update
+bundle exec brakeman --force --rails8 --path samples/rails --no-pager
+```
+
+The suite covers cryptographic vectors, tampering, replay/rotation, exact signed bytes, money, concurrent token caching, retries, real local TLS and Rails database transactions. Node.js supplies an independent JSON.stringify comparison. Tests use synthetic fixtures and move no funds; a registered TEST merchant is needed for a live acceptance run. See the [Rails guide](/sdks/rails) and repository [security policy](https://github.com/Lunixi-Payment/lunixi-ruby/blob/main/SECURITY.md).

data/docs/ruby.tr.md

@@ -0,0 +1,145 @@
+---
+title: Ruby SDK
+description: Lunixi Ruby SDK — kaynak kurulum, Ed25519 imza, ödeme ve fraud, kalıcı idempotency ve özgün baytlarla v2 webhook doğrulama.
+---
+
+
+# Ruby SDK
+
+`lunixi-sdk`, Lunixi için sunucu tarafı Ruby istemcisidir. Ed25519 imzayı OpenSSL ile üretir; token’ı eşzamanlı istekler arasında saklar, kompakt JavaScript uyumlu JSON oluşturur, güvenli tekrar denemeleri ve özgün baytlarla webhook doğrulamayı sağlar. Rails, Sinatra, Rack ve düz Ruby ile çalışır. Ana gem çerçeveden bağımsızdır; kaynak depodaki çalıştırılabilir [Rails örneği](/sdks/rails) ayrı adaptördür.
+
+## Gereksinimler ve kaynak kurulum
+
+Ruby **3.3+**, Bundler ve **Ed25519** destekli OpenSSL gerekir. Rails örneği Rails 8.1 kullanır.
+
+> 
+0.1.1 kaynak kod üzerinden dağıtılır. RubyGems yayını ayrı bir sürüm adımıdır; aşağıdaki kurulum yayımlanmış bir registry paketi varsaymaz.
+
+
+```bash
+git clone https://github.com/Lunixi-Payment/lunixi-ruby.git
+cd lunixi-ruby
+bundle install
+gem build lunixi-sdk.gemspec
+gem install ./lunixi-sdk-0.1.1.gem
+```
+
+Kaynak: [Lunixi-Payment/lunixi-ruby](https://github.com/Lunixi-Payment/lunixi-ruby). İncelenmiş yerel kopyayı `gem 'lunixi-sdk', path: '/tam/yol/lunixi-ruby'` ile kullanabilirsiniz. Bundler Git kaynağı kullanırken denetlenmiş commit’i sabitleyin.
+
+## İstemci ve anahtarlar
+
+```ruby
+require 'lunixi'
+
+lunixi = Lunixi::Client.new(
+  base_url: ENV.fetch('LUNIXI_BASE_URL'),
+  key_id: ENV.fetch('LUNIXI_KEY_ID'),
+  private_key: File.read(ENV.fetch('LUNIXI_PRIVATE_KEY_PATH')),
+  timeout: 30,
+  max_retries: 2
+)
+```
+
+`base_url`, `https://api-gateway.lunixi.com` gibi yalnız HTTPS origin olmalıdır; kullanıcı bilgisi, path, query veya fragment içeremez. TEST/LIVE ortamını anahtar belirler. Her üye işyeri bağlantısı için tek istemci oluşturup paylaşın; token önbelleği thread-safe çalışır.
+
+Sunucuda anahtar üretimi:
+
+```bash
+umask 077
+openssl genpkey -algorithm ED25519 -out lunixi-private.pem
+openssl pkey -in lunixi-private.pem -pubout -out lunixi-public.pem
+```
+
+Public anahtarı Lunixi paneline kaydedip verilen key id’yi kullanın. Özel anahtar kaynak kontrolüne ve public web dizinine girmemelidir. PKCS#8 PEM, base64 PKCS#8 DER, base64 32 bayt seed ve 64 bayt secret desteklenir. Bkz. [Kimlik doğrulama](/getting-started/authentication).
+
+## Ödeme intent’i
+
+İlk istekten önce ödeme denemesini ve UUID idempotency anahtarını kalıcı kaydedin. Toplamı tarayıcıdan almak yerine sunucuda hesaplayın.
+
+```ruby
+result = lunixi.payments.create_intent(
+  {
+    amount: 10_050,
+    currency: 'TRY',
+    orderId: order.public_id,
+    callbackUrl: 'https://merchant.example/payments/return',
+    basketItems: [{ id: 'item-1', name: 'Product', itemType: 'PHYSICAL', price: 10_050 }]
+  },
+  idempotency_key: order.persisted_payment_attempt_key
+)
+
+intent_id = result.fetch('data').fetch('paymentId')
+checkout_token = result.fetch('data').fetch('token')
+```
+
+`10_050`, 100,50 TRY’nin kuruş karşılığıdır. Intent’i kaydedin, checkout token’ını veritabanında şifreleyin. Rails örneği token’ı doğrulayıp sabit `https://pay.lunixi.com/payment/<token>` adresini kurar. Lunixi formu, üye işyerine açık yöntemleri ve uygun alternatif/çoklu kart akışlarını gösterir; kullanılabilirlik hesap ayarlarına bağlıdır. SDK ile PAN/CVV toplamayın.
+
+> 
+Intent/token, HTTP 2xx, dönüş sayfası veya ara split durumu tahsilat kanıtı değildir. İmzalı webhook’u kalıcı siparişle eşleştirin; sunucudan ödeme sorgusunda nihai durum, tutar ve para birimi uyuşmadan siparişi tamamlamayın.
+
+
+Tutarlar pozitif ve JavaScript güvenli tam sayı aralığında olmalıdır. Kök `price`/`paidPrice` null olsa bile reddedilir. Sepet ve split bacak toplamları ana toplamla aynı olmalıdır. Intent’te `installment` gönderilmez; taksit formda seçilir. `preauth: true` provizyon ister; capture ayrı işlemdir.
+
+## Yardımcı API’ler
+
+| İşlem | API |
+| --- | --- |
+| Intent | `lunixi.payments.create_intent(body, idempotency_key:)` |
+| Ödeme okuma/liste | `lunixi.payments.get(id)`, `lunixi.payments.list(**filters)` |
+| Açık yöntemler | `lunixi.payments.methods(payment_method: nil)` |
+| Capture | `lunixi.payments.capture(id, idempotency_key:, amount: nil)` |
+| Tam/kısmi iade | `lunixi.payments.refund(id, idempotency_key:, amount: nil, reason: nil)` |
+| Provizyon iptali | `lunixi.payments.void(id, idempotency_key:)` |
+| Split | `lunixi.payments.split(body, idempotency_key:)` |
+| Split durum/iade | `lunixi.payments.get_split(id)`, `lunixi.payments.refund_split(id, amount:, idempotency_key:, reason: nil)` |
+| Fraud | `lunixi.fraud.evaluate(body)`, `lunixi.fraud.record_event(body, idempotency_key:)` |
+| İmzalı genel HTTP | `lunixi.request(method, path, body: nil, query: {}, idempotency_key: nil, signed: true, binary: false)` |
+
+Capture/iade `amount: nil`, kalan tutarın gateway tarafından kullanılmasını ister. False, sıfır, string ve kesirli tutar reddedilir. Her capture/iade/iptal için ayrı, kalıcı anahtar saklayın. Belgelenmiş devam eden split durumlarındaki HTTP 400 yanıtları protokol sonucu olarak döndürülür; ödenmiş sayılmaz. Yanıt zarfı korunur.
+
+Diğer **dokümante** gateway uçları aynı imzalı transport üzerinden çağrılabilir:
+
+```ruby
+links = lunixi.request('GET', '/api/v1/payments/links', query: { limit: 20 })
+```
+
+Payment, fraud ve webhook için açık yardımcılar vardır. Diğer servisler yayımlanmış REST şemasıyla kullanılır; bu sürüm her ürün için ayrı tipli istemci sunduğunu iddia etmez.
+
+## Webhook
+
+JSON parse işleminden önce özgün baytları alın. Lunixi imza header’larını string değerlerle aktarın:
+
+```ruby
+verifier = Lunixi::WebhookVerifier.new(
+  secret: ENV.fetch('LUNIXI_WEBHOOK_SECRET'),
+  previous_secrets: []
+)
+
+verifier.process(raw_request_bytes, signature_headers, store: durable_transactional_store) do |event|
+  # Intent/sipariş ve sunucu ödeme sorgusuyla mutabakat yapın.
+  # Sipariş değişikliği ile olay kaydını aynı transaction içinde commit edin.
+end
+```
+
+v2 HMAC-SHA256, `eventId.timestamp.rawBody` üzerinde constant-time karşılaştırılır. İmzalı kimlik/tip tutarlılığı kontrol edilir; yinelenmiş JSON anahtarları reddedilir. Varsayılan geçmiş/gelecek zaman toleransı **300 saniyedir**. Rotasyonda en fazla iki önceki secret tutulabilir. Header isimleri büyük/küçük harfe duyarsızdır; yinelenmiş header reddedilir.
+
+Yalnız doğrulama olay kaydı oluşturmaz. Store `process_once(id:, digest:) { … }` uygular: benzersiz receipt ve sipariş değişikliği tek veritabanı transaction’ında commit edilir; `:processed` / `:duplicate` döner. Aynı kimliğin farklı baytları `Lunixi::ReplayConflict` üretir. İşleyici hatasında receipt geri alınmalıdır; yeniden teslim kurtarabilir. Kayıtları süreçler ve yeniden başlatmalar arasında koruyun. Rails örneğinde benzersiz `(connection_id, event_id)` indeksiyle gerçek veritabanı implementasyonu vardır.
+
+## Hatalar ve tekrar deneme
+
+Taban sınıf `Lunixi::Error`’dır. `ConfigurationError`, `SignatureError`, `TransportError`, `RedirectError`, `WebhookError` / `ReplayConflict` ve `ApiError` alt sınıfları ayrılır. API hatalarında `status`, güvenli `code` / `request_id` ve isteğe bağlı `retry_after` vardır; karşı tarafın gövdesi/hata metni eklenmez.
+
+GET/HEAD ve idempotency anahtarlı mutation, ağ hatası veya HTTP 429/502/503/504 için varsayılan iki, en çok üç kez tekrarlanabilir. Gövde/anahtar değişmez; nonce/imza yenilenir. Güvenli 401 çağrısında token bir kez yenilenir. Anahtarsız mutation tekrarlanmaz. Belirsiz zaman aşımında özgün işlemi sorgulayın; **yeni** anahtarla tahsilat başlatmayın.
+
+TLS sertifika/hostname doğrulaması zorunludur; yönlendirmeler ve path/credential enjeksiyonu engellenir. İstek 1 MiB, yanıt 8 MiB ile sınırlıdır. `transport:`, `clock:`, `sleeper:` testlerde enjekte edilebilir. Transport `Lunixi::Response.new(status:, headers:, body:)` döndürmeli ve TLS/yönlendirme/thread-safety koşullarını korumalıdır. `ca_file:` doğrulamayı kapatmadan özel CA sağlar; ortam proxy kimlik bilgileri otomatik aktarılmaz.
+
+## Testler ve Rails
+
+```bash
+bundle exec rake test rails:test
+bundle exec rubocop
+bundle exec bundle-audit check --update
+bundle exec brakeman --force --rails8 --path samples/rails --no-pager
+```
+
+Testler kriptografik vektörleri, bozulmuş imzayı, replay/rotasyonu, imzalanan baytları, tutarları, eşzamanlı token’ı, retry’ı, gerçek yerel TLS ve Rails transaction’larını kapsar. Node.js bağımsız JSON.stringify karşılaştırması sağlar. Sentetik testler para taşımaz; canlı kabul testi için kayıtlı TEST üye işyeri gerekir. [Rails rehberi](/sdks/rails) ve [güvenlik politikası](https://github.com/Lunixi-Payment/lunixi-ruby/blob/main/SECURITY.md).

data/lib/lunixi/checkout.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Lunixi
+  # Browser-safe configuration and strict backend-supplied optional hosted URLs.
+  module Checkout
+    def self.payment_page_url(value)
+      unless value.is_a?(String) && value.match?(%r{\Ahttps://pay\.lunixi\.com/payment/[A-Za-z0-9_.~-]{16,4096}\z})
+        raise Error, 'A valid backend paymentPageUrl is required'
+      end
+
+      value.dup.freeze
+    end
+
+    def self.browser_config(token)
+      raise Error, 'Checkout token is invalid' unless token.is_a?(String) && token.match?(/\A[A-Za-z0-9_.~-]{16,4096}\z/)
+
+      { type: 'payment', target: 'lunixi-checkout-form', options: { token: token } }
+    end
+  end
+end

data/lib/lunixi/client.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Lunixi
+  # Thread-safe server-side gateway client. Responses retain the gateway envelope.
+  class Client
+    AUTH_PATH = '/api/v1/auth/token'
+    METHODS = %w[GET HEAD POST PUT PATCH DELETE].freeze
+    attr_reader :payments, :fraud
+
+    def initialize(base_url:, key_id:, private_key:, timeout: 30, max_retries: 2, transport: nil,
+                   clock: -> { Time.now.utc }, sleeper: ->(seconds) { sleep(seconds) }, ca_file: nil)
+      @origin = validate_origin(base_url)
+      raise ConfigurationError, 'Invalid key id' unless key_id.is_a?(String) && key_id.match?(/\A[a-zA-Z0-9_.:-]{1,200}\z/)
+      raise ConfigurationError, 'timeout must be between 1 and 120 seconds' unless timeout.is_a?(Numeric) && timeout.between?(1, 120)
+      raise ConfigurationError, 'max_retries must be between 0 and 3' unless max_retries.is_a?(Integer) && max_retries.between?(0, 3)
+
+      @key_id = key_id.dup.freeze
+      @signer = Signer.new(private_key)
+      @transport = transport || NetHttpTransport.new(timeout: timeout, ca_file: ca_file)
+      @max_retries = max_retries
+      @clock = clock
+      @sleeper = sleeper
+      @token_mutex = Mutex.new
+      @token = nil
+      @token_expires_at = Time.at(0)
+      @payments = Payments.new(self)
+      @fraud = Fraud.new(self)
+    end
+
+    # Advanced, signed transport for other documented gateway surfaces. It does
+    # not invent field schemas, interpret financial results or retry an unsafe POST.
+    def request(method, path, body: nil, query: {}, idempotency_key: nil, signed: true, binary: false)
+      method = method.to_s.upcase
+      raise ConfigurationError, 'Unsupported HTTP method' unless METHODS.include?(method)
+      raise ConfigurationError, 'GET and HEAD cannot have a body' if %w[GET HEAD].include?(method) && !body.nil?
+
+      path = safe_path(path, query)
+      key = self.class.idempotency_key!(idempotency_key) if idempotency_key
+      bytes = body.nil? ? nil : JsonBody.dump(body)
+      raise ConfigurationError, 'Request body exceeds the size limit' if bytes && bytes.bytesize > 1024 * 1024
+
+      perform_request(method, path, bytes, key, signed, binary)
+    end
+
+    # Validates caller-owned durable keys; a generated key on every retry is unsafe.
+    def self.idempotency_key!(key)
+      unless key.is_a?(String) && key.match?(/\A[\x21-\x7e]{16,128}\z/)
+        raise ConfigurationError, 'Idempotency key must be 16–128 printable ASCII characters without spaces'
+      end
+
+      key.dup.freeze
+    end
+
+    def inspect
+      '#<Lunixi::Client credentials=[REDACTED]>'
+    end
+
+    private
+
+    def perform_request(method, path, bytes, key, signed, binary)
+      safe_to_retry = %w[GET HEAD].include?(method) || !key.nil?
+      retries = 0
+      reauthenticated = false
+      loop do
+        token = access_token
+        response = transmit(method, path, bytes, key, token, signed)
+        if response.status == 401 && !reauthenticated && safe_to_retry
+          invalidate_token(token)
+          reauthenticated = true
+          next
+        end
+        if retryable_response?(response, safe_to_retry, retries)
+          pause(retries, response.headers)
+          retries += 1
+          next
+        end
+        return decode_response(response, binary: binary, running_split: method == 'POST' && path == '/api/v1/payments/split')
+      rescue TransportError
+        raise unless safe_to_retry && retries < @max_retries
+
+        pause(retries, {})
+        retries += 1
+      end
+    end
+
+    def retryable_response?(response, safe_to_retry, retries)
+      [429, 502, 503, 504].include?(response.status) && safe_to_retry && retries < @max_retries
+    end
+
+    def validate_origin(value)
+      uri = URI.parse(value)
+      unless uri.is_a?(URI::HTTPS) && uri.host && !uri.userinfo && !uri.query && !uri.fragment && ['', '/'].include?(uri.path)
+        raise ConfigurationError, 'base_url must be an HTTPS origin without credentials, path, query or fragment'
+      end
+
+      value.delete_suffix('/').freeze
+    rescue URI::InvalidURIError, TypeError
+      raise ConfigurationError, 'Invalid HTTPS gateway origin', cause: nil
+    end
+
+    def safe_path(path, query)
+      unless path.is_a?(String) && path.start_with?('/api/v1/') && path.match?(%r{\A/[a-zA-Z0-9_~./%-]+\z})
+        raise ConfigurationError, 'Only relative /api/v1/ gateway paths are accepted'
+      end
+
+      path.split('/').each do |segment|
+        decoded = URI::RFC2396_PARSER.unescape(segment)
+        raise ConfigurationError, 'Unsafe gateway path segment' if ['.', '..'].include?(decoded) || decoded.match?(%r{[\\/\x00-\x20\x7f%]})
+      end
+      encoded = encoded_query(query)
+      encoded.empty? ? path : "#{path}?#{encoded}"
+    end
+
+    def encoded_query(query)
+      raise ConfigurationError, 'Query must be a hash' unless query.is_a?(Hash)
+
+      pairs = query.flat_map do |name, value|
+        raise ConfigurationError, 'Invalid query key' unless name.to_s.match?(/\A[a-zA-Z][a-zA-Z0-9_]{0,63}\z/)
+
+        Array(value).map do |entry|
+          unless entry.is_a?(String) || entry.is_a?(Integer) || entry == true || entry == false
+            raise ConfigurationError, 'Query values must be strings, integers or booleans'
+          end
+          raise ConfigurationError, 'Query value is too long' if entry.to_s.bytesize > 4096
+
+          [name.to_s, entry.to_s]
+        end
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    def signed_headers(method, path, body)
+      date = @clock.call.getutc.iso8601
+      nonce = SecureRandom.uuid
+      digest = Signer.digest(body) unless body.nil?
+      headers = { 'X-Key-Id' => @key_id, 'X-Date' => date, 'X-Nonce' => nonce }
+      headers['Digest'] = digest if digest
+      headers['X-Signature'] = @signer.sign(Signer.canonical(method, path, date, nonce, digest))
+      headers
+    end
+
+    def transmit(method, path, body, key, token, signed)
+      headers = { 'Accept' => 'application/json', 'User-Agent' => "lunixi-sdk-ruby/#{VERSION}" }
+      headers['Authorization'] = "Bearer #{token}" if token
+      headers['Content-Type'] = 'application/json' unless body.nil?
+      headers['Idempotency-Key'] = key if key
+      headers.merge!(signed_headers(method, path, body)) if signed
+      response = @transport.call(method: method, uri: URI.parse(@origin + path), headers: headers.freeze, body: body)
+      unless response.is_a?(Response) && response.status.is_a?(Integer) && response.headers.is_a?(Hash) && response.body.is_a?(String)
+        raise TransportError, 'Transport returned an invalid response'
+      end
+      raise TransportError, 'Gateway response exceeds the size limit' if response.body.bytesize > NetHttpTransport::MAX_RESPONSE_BYTES
+      raise RedirectError, 'Gateway redirects are rejected; credentials were not forwarded' if response.status.between?(300, 399)
+
+      response
+    end
+
+    def access_token
+      @token_mutex.synchronize do
+        return @token if @token && @clock.call < @token_expires_at
+
+        response = transmit('POST', AUTH_PATH, nil, nil, nil, true)
+        payload = decode_response(response)
+        data = payload['data'].is_a?(Hash) ? payload['data'] : payload
+        token = data['access_token'] || data['accessToken']
+        ttl = data['expires_in'] || data['expiresIn']
+        unless token.is_a?(String) && token.match?(/\A[a-zA-Z0-9_.:-]{1,8192}\z/) && ttl.is_a?(Integer) && ttl.positive? && ttl <= 86_400
+          raise AuthenticationError.new(status: 502, code: 'invalid_token_response')
+        end
+
+        @token = token.freeze
+        @token_expires_at = @clock.call + [ttl - 30, 1].max
+        token
+      end
+    end
+
+    def invalidate_token(previous)
+      @token_mutex.synchronize { @token = nil if @token == previous }
+    end
+
+    def pause(attempt, headers)
+      retry_after = headers['retry-after'] || headers['Retry-After']
+      seconds = retry_after.to_s.match?(/\A\d{1,3}\z/) ? [retry_after.to_i, 5].min : [0.1 * (2**attempt), 2].min
+      @sleeper.call(seconds)
+    end
+
+    def decode_response(response, binary: false, running_split: false)
+      return response.body.b.freeze if binary && response.status.between?(200, 299)
+
+      begin
+        payload = response.body.empty? ? {} : JSON.parse(response.body, max_nesting: 64)
+      rescue JSON::ParserError
+        raise ApiError.new(status: response.status, code: 'invalid_json_response'), cause: nil
+      end
+      raise ApiError.new(status: response.status, code: 'invalid_json_response') unless payload.is_a?(Hash)
+      return payload if response.status.between?(200, 299)
+
+      error_class = case response.status
+                    when 401, 403 then AuthenticationError
+                    when 400, 422 then ValidationError
+                    when 429 then RateLimitError
+                    else ApiError
+                    end
+      error = error_class.new(status: response.status, code: payload['code'],
+                              request_id: response.headers['x-request-id'] || response.headers['X-Request-Id'],
+                              retry_after: response.headers['retry-after'])
+      # Running split sessions are successful protocol responses, not completed payments.
+      running = %w[COMPOSING AUTHORIZING AWAITING_3DS AWAITING_ACTION AWAITING_CREDIT_APPROVAL AWAITING_REPLACEMENT_CARD AUTHORIZED CAPTURING]
+      return payload if running_split && response.status == 400 && running.include?(payload['code']) && payload.dig('data', 'splitPaymentId').is_a?(String)
+
+      raise error
+    end
+  end
+end