Ön Provizyon, Capture & İptal

Ön provizyonda (pre-authorization) ödeme anında çekilmez: alıcının bankası tutarı bloke eder, ödeme AUTHORIZED durumunda bekler. Siparişi karşılamaya hazır olduğunuzda tutarın tamamını ya da bir kısmını capture ile çekersiniz; siparişi karşılamayacaksanız void ile blokeyi kaldırırsınız.

Tipik kullanımlar: kargoya verildiğinde çekim, depozito ve rezervasyon, kısmi karşılanan siparişler, inceleme bitene kadar bekletilen ödemeler. Aynı bloke, capture ve void modeli parçalı ödemenin kart parçalarında da kullanılır.

Ön provizyonu ödeme isteğindeki preauth alanıyla istersiniz. Bu sayfa ön provizyonun bütün kurallarını tek yerde anlatır; ödeme sayfaları kendi isteklerindeki alanı gösterip buraya bağlanır.

Nasıl çalışır

Ön provizyonu isteme

Ayrı bir ön provizyon ucu yoktur. preauth alanını ödemeyi başlatan istekte gönderirsiniz:

Alanın kuralları iki istekte de aynıdır:

Ön provizyon talimatı hiçbir koşulda sessizce anında çekime dönüştürülmez. Talimatı yerine getiremeyen bir sağlayıcıya ödeme gönderilmez; ödeme ya başka uygun sağlayıcıya yönlendirilir ya da açık bir hatayla reddedilir (bkz. Hangi yöntemler destekler).

{
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-84722",
  "callbackUrl": "https://shop.example.com/payment/result",
  "preauth": true
}

Hangi yöntemler destekler

Ön provizyonu ödemeyi gerçekleştiren sağlayıcının desteklemesi gerekir.

Kart

• 2D: Ön provizyonu desteklemeyen sağlayıcılar adaylardan çıkarılır ve ödeme destekleyen bir sağlayıcıya yönlendirilir. Uygun sağlayıcı kalmazsa ödeme FAILED olur ve ret kodu PREAUTH_NOT_SUPPORTED'dır.
• 3D Secure: Sağlayıcının ön provizyonu 3D Secure ile de desteklemesi gerekir. Desteklemeyen sağlayıcılar adaylardan çıkarılır. Uygun sağlayıcı kalmazsa ödeme FAILED olur ve ret kodu PREAUTH_3DS_NOT_SUPPORTED'dır. 3D Secure ile ön provizyonu destekleyen hiçbir sağlayıcı yoksa istek ödeme başlamadan 422 payment.preauth.three_ds_unsupported ile reddedilir.
• 3D Secure akışında alıcı banka doğrulamasını tamamladığında para çekilmez; ödeme AUTHORIZED olur.

Kart dışı yöntemler

• Bir yöntemin ve sağlayıcının ön provizyonu destekleyip desteklemediği GET /payments/methods yanıtındaki preauth alanındadır (yöntem satırında ve her sağlayıcıda).
• Desteklemeyen yöntemle preauth: true gönderirseniz istek 422 payment.preauth.unsupported_for_method ile reddedilir. Ödeme başlatılmaz, tutar çekilmez.
• Checkout Formu'nda ön provizyonlu bir intent için yalnız ön provizyonu destekleyen yöntemler ve sağlayıcılar gösterilir.

Capture

POST /payments/{id}/capture, AUTHORIZED ödemenin tutarını çeker. Uç Step-Up ister (Bearer token ve Ed25519 imzası; bkz. Kimlik Doğrulama).

• amount yetkilendirilen tutardan küçükse kısmi capture yapılır ve durum PARTIALLY_CAPTURED olur. Kalan tutarı sonraki capture isteğiyle çekebilirsiniz; toplam çekim yetkilendirilen tutara ulaştığında durum CAPTURED olur.
• Toplam çekim yetkilendirilen tutarı aşamaz; aşan istek 400 payment.capture.amount_exceeded ile reddedilir.

# Step-Up imza başlıklarının nasıl hesaplandığı için Kimlik Doğrulama sayfasına bakın.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30/capture \
  -H "Authorization: Bearer at_test_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: mk_test_sk_..." \
  -H "X-Date: 2026-10-11T09:00:00.000Z" \
  -H "X-Nonce: 3c1d8e2a-7b4f-4e6a-9d0c-5a2b1e8f7c64" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: cap-ORD-84722-1" \
  -d '{
    "paymentIntentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "amount": 7500
  }'

Capture yanıtı

{
  "status": "success",
  "code": "PAYMENT_PARTIALLY_CAPTURED",
  "message": "…",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "amount": 10050,
    "currency": "TRY",
    "status": "PARTIALLY_CAPTURED"
  },
  "details": {
    "capturedAmount": "7500",
    "refundedAmount": "0",
    "remainingCapturable": "2550",
    "remainingRefundable": "7500"
  },
  "statusCode": 200,
  "requestId": "…"
}

Tam capture'da code PAYMENT_CAPTURED, data.status CAPTURED olur. details içindeki tutarlar minor unit metin olarak döner.

Void

POST /payments/{id}/void, capture edilmemiş bir ön provizyonu kaldırır; para hareket etmez ve ödeme VOIDED olur. Uç API anahtarı imzasını ya da panel oturumunu kabul eder; API ile çağırırken Kimlik Doğrulama sayfasındaki imza başlıklarını gönderin.

• Idempotency-Key zorunludur; yoksa istek 400 payment.operation.idempotency_key_required ile reddedilir.
• Gövde boştur ({}).
• Yanıtta code PAYMENT_VOIDED, data.status VOIDED olur.

# Step-Up imza başlıklarının nasıl hesaplandığı için Kimlik Doğrulama sayfasına bakın.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30/void \
  -H "Authorization: Bearer at_test_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: mk_test_sk_..." \
  -H "X-Date: 2026-10-11T09:00:00.000Z" \
  -H "X-Nonce: 6e2a9c41-0d3b-4f7a-8b15-9c4e2d1f7a03" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: void-ORD-84722-1" \
  -d '{}'

Void yanıtı

{
  "status": "success",
  "code": "PAYMENT_VOIDED",
  "message": "…",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "amount": 10050,
    "currency": "TRY",
    "status": "VOIDED"
  },
  "statusCode": 200,
  "requestId": "…"
}

Süre dolumu

• Capture ya da void yapılmayan ön provizyon, ödemenin açılışından 7 gün sonra platformda EXPIRED (son durum) olur ve payment.expired webhook'u gönderilir. Süre hesap bazında değiştirilemez.
• EXPIRED olan ödeme artık capture edilemez.
• Karttaki bloke bu olayla kalkmaz. Bankaya iptal gönderilmez; bloke bankanın kendi süresiyle düşer. Blokeyi erken kaldırmak için süre dolmadan void yapın.

Durumlar

Bütün durumlar için bkz. Ödeme Listeleme.

Hatalar

Hata kodları

Webhook'lar

Teslimat ve imza doğrulama için bkz. Webhook'lar.

Sonraki adımlar

• Checkout Formu — intent oluşturma ve form
• Kart — 2D ve Kart — 3D Secure — kartla ödeme
• Payment — bütün yöntemler tek uçtan
• İade — çekilmiş parayı geri verme