Link Oluşturma

POST /api/v1/payments/links yeni bir ödeme linki oluşturur ve paylaşacağınız https://pay.lunixi.com/<KOD> adresini döner. Bu sayfa kimlik doğrulamayı, isteğin bütün alanlarını, yanıtı ve hataları anlatır. Linki panelden de oluşturabilirsiniz; bu sayfa sunucunuzdan yapılan API entegrasyonu içindir.

Nasıl çalışır

Kimlik doğrulama

Ödeme linki uçları (/api/v1/payments/links/*) yalnız API anahtarınızla imzalanmış istek kabul eder. Her istek aşağıdaki başlıkları taşır; Authorization başlığı gerekmez. Bearer erişim token'ı ya da panel oturumu bu uçlarda kimlik yerine geçmez — imza başlıkları olmayan istek 401 AUTH_HEADERS_MISSING alır.

İmzalanan metin, satırları \n ile birleştirilmiş şu yapıdır (örnekteki Digest, aşağıdaki örnek isteğin gövdesine aittir):

POST
/api/v1/payments/links
X-Date:2026-09-25T09:00:00Z
X-Nonce:64ae70b60739b3515d972c0378854a59
Digest:SHA-256=DshE/z0IEfWv/itO+8GjSJCAVm7v4gZyyw7vIML0Edo=

Bu bölümdeki Node.js örnekleri aşağıdaki signedHeaders yardımcısını kullanır. Özel anahtarınız sunucunuzda kalır; tarayıcıya ya da mobil uygulamaya asla konmaz.

import { createHash, createPrivateKey, sign, randomUUID } from 'node:crypto';
 
export const BASE_URL = 'https://api-gateway.lunixi.com';
const signingKey = createPrivateKey(process.env.LUNIXI_SIGNING_KEY_PEM);
 
// pathWithQuery: sorgu dizesi dahil tam yol, ör. '/api/v1/payments/links?limit=25'
// body: gönderdiğiniz JSON dizesinin kendisi; gövdesiz istekte verilmez
export function signedHeaders(method, pathWithQuery, body) {
  const date = new Date().toISOString();
  const nonce = randomUUID();
  const headers = { 'X-Key-Id': process.env.LUNIXI_KEY_ID, 'X-Date': date, 'X-Nonce': nonce };
  const lines = [method, pathWithQuery, `X-Date:${date}`, `X-Nonce:${nonce}`];
  if (body !== undefined) {
    const digest = 'SHA-256=' + createHash('sha256').update(body).digest('base64');
    headers['Content-Type'] = 'application/json';
    headers['Digest'] = digest;
    lines.push(`Digest:${digest}`);
  }
  headers['X-Signature'] = sign(null, Buffer.from(lines.join('\n')), signingKey).toString('base64');
  return headers;
}

cURL örnekleri imzayı OpenSSL 3.0 veya üstü ile hesaplar (openssl pkeyutl -rawin). Anahtar kaydı ve döndürme: Kimlik Doğrulama.

Yetkiler

İmza doğrulandıktan sonra anahtarın yetkisi (scope) kontrol edilir. Eksik yetki 403 API_INSUFFICIENT_SCOPE döner.

Ortam

Linkin ortamını (TEST ya da LIVE) anahtarınızın ortamı belirler. Gövdede environment göndermeniz gerekmez; gönderirseniz anahtarınızın ortamıyla aynı olmalıdır, aksi hâlde 403 payment_link.environment.mismatch döner. Bir anahtar yalnız kendi ortamındaki linkleri görür ve değiştirir.

İstek

POST /api/v1/payments/links — imzalı istek, yetki payment-link:create.

Idempotency-Key

Zorunludur. 8–200 karakter, boşluksuz yazdırılabilir ASCII (^[\x21-\x7E]{8,200}$). Linki tanımlayan bir değer kullanın — ör. plink-INV-2026-0042.

• Aynı anahtar + aynı gövde → yeni link oluşturulmaz; bu anahtarla oluşturulmuş link 200 ve replayed: true ile döner. Ağ zaman aşımında güvenle tekrar deneyebilirsiniz.
• Aynı anahtar + farklı gövde → 409 payment_link.idempotency.conflict.
• Anahtar yoksa 400 payment_link.idempotency.key_required, biçim dışıysa 400 payment_link.idempotency.key_invalid.

Alanlar

Tanımlanmamış bir alan ya da yanlış tip 400 VALIDATION_ERROR döner. İş kuralı ihlali (ör. FIXED linkte amountMinor yok) 422 payment_link.validation.invalid döner ve details.errors hangi alanın neden reddedildiğini listeler.

items[]

buyerFields

Her alan HIDDEN | OPTIONAL | REQUIRED değerlerinden birini alır.

customFields[]

Cevaplar string olarak saklanır: CHECKBOX için "true" / "false", DATE için YYYY-MM-DD. Dosya yükleme alanı yoktur.

recipient ve prefill

• recipient — { name, email, phone } (ad en fazla 120, e-posta en fazla 180 karakter, telefon E.164). Linki belirli bir kişiye gönderiyorsanız doldurun: POST /:id/send ve hatırlatmalar varsayılan olarak bu adrese gider, erişim doğrulama kodu yalnız bu e-postaya gönderilir. Ödeme sayfasında yalnız maskeli hâli görünür.
• prefill — { name, surname, email, phone, identityNumber, address, city, country, zipCode } (country ISO 3166-1 alpha-2). Bu bilgiler alıcının tarayıcısına gönderilmez; ödeme kaydının alıcı bilgilerine sunucuda yazılır. Alıcının formda girdiği değerler yalnız boş kalan alanları doldurur. Linke erişim doğrulaması eklediyseniz, doğrulamayı geçen alıcı bu bilgileri formda görür — identityNumber hariç.

Her iki nesne de şifreli saklanır ve yalnız sizin API yanıtlarınızda açık döner.

checkout

Örnek istek

# OpenSSL 3.0+ gerekir. Gövde boşluksuz JSON olmalıdır.
KEY_ID="mk_test_sk_..."             # X-Key-Id
KEY_FILE="lunixi-signing.key"       # Ed25519 özel anahtarınız (PEM)
REQ_PATH="/api/v1/payments/links"
BODY='{"usage":"SINGLE_USE","amountMode":"FIXED","currency":"TRY","amountMinor":150000,"title":"Kasım danışmanlık bedeli","expiresAt":"2026-10-31T20:59:59.000Z","reference":"INV-2026-0042","recipient":{"name":"Ayşe Yılmaz","email":"[email protected]"},"metadata":{"crmId":"A-77"}}'
 
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
NONCE=$(openssl rand -hex 16)
DIGEST="SHA-256=$(printf '%s' "$BODY" | openssl dgst -sha256 -binary | base64)"
printf 'POST\n%s\nX-Date:%s\nX-Nonce:%s\nDigest:%s' "$REQ_PATH" "$DATE" "$NONCE" "$DIGEST" > canonical.txt
SIGNATURE=$(openssl pkeyutl -sign -inkey "$KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: plink-INV-2026-0042" \
  --data-raw "$BODY"

Farklı link tipleri için gövde örnekleri:

// Bağış — alıcı tutarı girer, önerilen tutar düğmeleri
{ "usage": "MULTI_USE", "amountMode": "OPEN", "currency": "TRY",
  "minAmountMinor": 5000, "suggestedAmountsMinor": [10000, 25000, 50000],
  "title": "Kış kampanyası bağışı", "buttonLabelKey": "DONATE" }
 
// Bilet — sabit fiyat, adet seçimi, 200 kişilik kapasite
{ "usage": "MULTI_USE", "amountMode": "FIXED", "currency": "TRY",
  "amountMinor": 45000, "quantityEnabled": true, "minQuantity": 1, "maxQuantity": 4,
  "capacity": 200, "title": "Atölye — 12 Kasım", "eventAt": "2026-11-12T16:00:00.000Z" }
 
// Kalemli — beden seçimi, kalem başına stok
{ "usage": "MULTI_USE", "amountMode": "ITEMIZED", "currency": "TRY",
  "title": "Takım forması",
  "items": [
    { "itemKey": "forma_m", "name": "Forma — M", "unitPriceMinor": 90000, "maxQuantity": 3, "capacity": 40 },
    { "itemKey": "forma_l", "name": "Forma — L", "unitPriceMinor": 90000, "maxQuantity": 3, "capacity": 40 }
  ] }

Yanıt

201 Created — tekrar isteğinde 200 OK ve replayed: true.

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "id": "5f0c1d2e-8a4b-4c6d-9e7f-1a2b3c4d5e6f",
    "shortCode": "7KQ2M9XAPT",
    "url": "https://pay.lunixi.com/7KQ2M9XAPT",
    "organizationId": "b1d2c3e4-…",
    "environment": "TEST",
    "state": "ACTIVE",
    "version": 1,
    "rowVersion": 1,
    "createdBy": { "type": "API_KEY", "id": "mk_test_sk_…" },
    "createdAt": "2026-09-25T09:00:00.000Z",
    "updatedAt": "2026-09-25T09:00:00.000Z",
    "completedAt": null,
    "expiredAt": null,
    "deactivatedAt": null,
    "takedown": null,
    "verificationLocked": false,
    "hasActiveAttempt": false,
    "amountLocked": false,
    "counters": {
      "paidCount": 0, "collectedAmountMinor": 0, "refundedAmountMinor": 0,
      "soldQuantity": 0, "reservedQuantity": 0, "attemptCount": 0
    },
    "availability": { "soldOut": false, "remainingQuantity": null, "inProgress": false, "items": [] },
    "usage": "SINGLE_USE",
    "amountMode": "FIXED",
    "currency": "TRY",
    "amountMinor": 150000,
    "title": "Kasım danışmanlık bedeli",
    "expiresAt": "2026-10-31T20:59:59.000Z",
    "reference": "INV-2026-0042",
    "recipient": { "name": "Ayşe Yılmaz", "email": "[email protected]", "phone": "" },
    "metadata": { "crmId": "A-77" },
    "replayed": false
  },
  "statusCode": 201,
  "requestId": "req_7f3d9c1a4b2e"
}

Yanıt, gönderdiğiniz bütün alanları varsayılanlarıyla birlikte düz olarak içerir (örnekte kısaltıldı). Ayarlanmamış zaman alanları ve isteğe bağlı kimlikler null döner. Linkin kendi alanları:

Hatalar

Hata zarfı ve code üzerinden dallanma kuralı: Hata Yönetimi.

4xx hataları aynı istekle tekrar denenerek düzelmez; önce isteği düzeltin. 5xx yanıtlarında (ör. 503, 504) isteği aynı Idempotency-Key ve aynı gövdeyle üstel geri çekilmeyle yeniden deneyin: link ilk denemede oluşturulduysa ikinci bir link açılmaz, kayıtlı link replayed: true ile döner.

Webhook'lar

Link oluşturulduğunda payment.link.created yayınlanır. Ödeme ve link event'lerinin tamamı: Webhook'lar.

Sonraki adımlar

• Linkleri Yönetme — listeleme, güncelleme, duraklatma, gönderme, QR
• Ödeme Sayfası — alıcının gördüğü sayfa, marka ve erişim doğrulaması
• Webhook'lar — payment.captured ile siparişi teslim etme