Kimlik Doğrulama

Payment Orchestrator API'si, çağrıyı kimin yaptığına (sunucunuz, alıcının tarayıcısı, herkese açık siteniz) ve işlemin ne kadar hassas olduğuna göre farklı kimlik doğrulama modelleri kullanır. Bu sayfa her modeli çalışan örneklerle anlatır, ardından her endpoint grubunu gerektirdiği modele eşler.

Tüm örnekler için base URL: https://api-gateway.lunixi.com/api/v1.

Bearer erişim token'ı

Sunucudan sunucuya çağrıları kısa ömürlü bir erişim token'ı doğrular. Token'ı statik bir anahtar olarak saklamazsınız — kayıtlı Ed25519 anahtarınızla imzalayıp POST /api/v1/auth/token'dan basarsınız.

Ed25519 özel anahtar  ──imzala──▶  POST /api/v1/auth/token  ──▶  at_live_…  (~5 dk)

Aldığınız token'ı Authorization header'ında gönderin:

curl "https://api-gateway.lunixi.com/api/v1/payments?limit=20" \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Step-Up: para hareketi için imzalı istekler

Para hareketi yapan her endpoint — intent oluşturma, direct çekim, capture, void, refund — Step-Up auth ister: geçerli bir Bearer key ve isteğin üzerine bir Ed25519 imzası. Secret key'iniz sızsa bile, saldırgan özel imza anahtarınız olmadan para hareket ettiremez.

Bir Step-Up isteği şu header'ları taşır:

İmzalayacağınız string; method, tam istek path'i ve header'lardan \n ile birleştirilerek oluşturulur:

POST
/api/v1/payments/intents
X-Date:2026-07-06T12:00:00.000Z
X-Nonce:9f8d2c4e-1a3b-4c5d-8e7f-0a1b2c3d4e5f
Digest:SHA-256=k6I5cUt...=

import { createHash, createPrivateKey, sign, randomUUID } from 'node:crypto';
 
const body = JSON.stringify({
  amount: 10050,               // minor unit (kuruş) — ₺100,50
  currency: 'TRY',
  orderId: 'ORD-9988',
});
 
const digest = 'SHA-256=' + createHash('sha256').update(body).digest('base64');
const date = new Date().toISOString();
const nonce = randomUUID();
 
const canonical = [
  'POST',
  '/api/v1/payments/intents',
  `X-Date:${date}`,
  `X-Nonce:${nonce}`,
  `Digest:${digest}`,
].join('\n');
 
const signature = sign(
  null, // Ed25519 — digest algoritması yok
  Buffer.from(canonical),
  createPrivateKey(process.env.LUNIXI_SIGNING_KEY_PEM),
).toString('base64');
 
const res = await fetch('https://api-gateway.lunixi.com/api/v1/payments/intents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LUNIXI_SECRET_KEY}`,
    'Content-Type': 'application/json',
    'X-Key-Id': process.env.LUNIXI_KEY_ID,
    'X-Date': date,
    'X-Nonce': nonce,
    'Digest': digest,
    'X-Signature': signature,
    'Idempotency-Key': randomUUID(),
  },
  body,
});

Checkout form token & session-proof cookie (alıcı tarafı)

Hosted checkout formu, key'lerinizi hiç ifşa etmeden alıcının tarayıcısını doğrular:

1. Sunucunuz Step-Up auth ile bir intent oluşturur. Yanıt, allowedOrigin'inize bağlı, kısa ömürlü (~15 dakika) bir form token içerir.
2. Form bu token ile POST /payments/form/live-analyze çağırır; yanıt, tarayıcı oturumunu bağlayan bir session-proof cookie set eder.
3. Her /payments/form/* çağrısı token'ı taşır; karta dokunan çağrılar (/form/tokenize, /form/2d, /form/3d) ek olarak session-proof cookie'yi ister.

curl -X POST "https://api-gateway.lunixi.com/api/v1/payments/form/live-analyze" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{ "token": "<intent-ten-gelen-form-token>" }'

Publishable key + Origin allow-list

Publishable key (mk_live_pk_…) herkese açık sitenize gömülmesi güvenli olan key'dir. Yalnızca salt-okunur public catalog endpointlerini açar ve istekler ayrıca kayıtlı Origin allow-list'inize karşı denetlenir — çalınan bir key başka bir domain'den işe yaramaz.

curl "https://api-gateway.lunixi.com/api/public/v1/subscription/plans" \
  -H "Authorization: Bearer mk_live_pk_xxxxxxxxxxxx" \
  -H "Origin: https://shop.example.com"

/api/public/v1/subscription/plans|products|branding tarafından kullanılır — sitenize pricing gömmek için. Bkz. Pricing & Portal SDK.

Idempotency

Her ödeme POST'unda bir Idempotency-Key header'ı gönderin (benzersiz herhangi bir string, örn. UUID). Aynı key tekrar gelirse — ağ zaman aşımı, çift tıklanan buton, tekrar deneyen bir job — API çifte çekim yapmak yerine orijinal sonucu döner. Tekilleştirme Redis ile, Redis erişilemezse veritabanı benzersizliğiyle desteklenir.

curl -X POST "https://api-gateway.lunixi.com/api/v1/payments/pay_01JZ8K4W9X2R/refund" \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Idempotency-Key: refund-ORD-9988-1" \
  ... # Step-Up imza header'ları
  -d '{ "amount": 5000 }'

Hangi endpoint hangi modeli ister

Hatalar

Sonraki adımlar

• Hızlı Başlangıç — Step-Up akışını kullanıp ilk ödemenizi alın
• Checkout Formu — eksiksiz intent-create referansı
• Webhook'lar — imzalı event teslimatlarını doğrulayın