Fiziksel POS
Ödeme İşlemleri
Ön Provizyon

Ön Provizyon

Bu uçları kim çağırır?Dış API (s2s)
Taban yol
/api/v1/physical-pos
Kimlik
Her istekte Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, X-Signature; gövdeli isteklerde ayrıca Digest. Zaman penceresi ±5 dk, nonce tek kullanımlık. Bearer jetonu ya da panel oturumu bu uçlarda kabul edilmez.
Yetki
Anahtarınız Fiziksel POS ürününü (PHYSICAL_POS) ve bu sayfadaki uçların kapsamını taşımalıdır: physical_pos:payments. Ürünü olmayan anahtar 403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar 403 API_INSUFFICIENT_SCOPE alır. Bkz. Kimlik Doğrulama ve Kapsamlar.
Çapraz yüzey
Bu uçlar s2s yüzeyindedir; kendi sunucunuzdan imzalı istekle çağırırsınız. Aynı kayıtların panelde ekranları var, ama panel uçları API anahtarıyla çağrılamaz; bu uçlar da panel oturumuyla çağrılamaz.

Kartta bir tutarı bloke edip sonra kesinleştirirsiniz (otel, araç kiralama gibi). Akış üç adımdır: açma, kapama (tahsil) ya da iptal.

AdımUçoperation
Ön provizyon açmaPOST /api/v1/physical-pos/paymentsPREAUTH_OPEN
Kapama (tahsil)POST /api/v1/physical-pos/payments/{paymentId}/reversalsPREAUTH_CLOSE
İptal (blokeyi kaldırma)POST /api/v1/physical-pos/payments/{paymentId}/reversalsPREAUTH_CANCEL

Üç adım da physical_pos:payments kapsamı ve Idempotency-Key ister.

Açma

İstek satış ile aynıdır; operation: "PREAUTH_OPEN". Taksit (installmentCount) ve kalem (items) gönderilmez.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
BODY='{"operation":"PREAUTH_OPEN","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"50000","currency":"TRY","merchantReference":"RES-2026-000045"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 5c1e7a90-2f4b-4d38-b6a1-9e0f1a2b3c4d" \
  --data-raw "$BODY"

Kapama

Bloke edilen tutarı tahsil edersiniz. amountMinor zorunludur.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"PREAUTH_CLOSE","amountMinor":"42000","currency":"TRY"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 7e3b5c10-8a2d-4f61-9b47-2c3d4e5f6a7b" \
  --data-raw "$BODY"
  • Ön provizyon açık olmalıdır (reversalStatus: "NONE"); aksi 409 physical_pos.payment.not_reversible (preauth_not_open).
  • Tutar en çok, onaylanan tutar artı cihaz modelinin izin verdiği paydır; aşarsa 400 physical_pos.payment.amount_invalid (preauth_close_exceeds_tolerance).
  • Açık tutardan az kapama, cihaz modelinin kısmi kapamayı desteklemesini gerektirir; aksi 422 … partial_amount_unsupported.
  • Kapama onaylanınca asıl ödemede reversalStatus: "PREAUTH_CLOSED" olur, tahsil edilen tutar capturedMinor alanındadır.

İptal

Blokeyi kaldırırsınız; tutar gönderilmez ({"operation":"PREAUTH_CANCEL","currency":"TRY"}). Ön provizyon açık olmalıdır. Onaylanınca reversalStatus: "PREAUTH_CANCELLED" olur.

Kapamadan sonra

  • Kapamanın iptali: VOID ile tahsil edilen tutarın tamamı geri alınır. → İptal (Void)
  • İade: REFUND ile tahsil edilen tutardan en çok capturedMinor − reversedMinor kadar iade edilir. → İade
  • Kapanmamış ön provizyon iade ya da void edilemez: 409 … refund_preauth_not_closed / void_preauth_not_closed; iptal edin.
  • Süresi dolan ön provizyonda reversalStatus: "PREAUTH_EXPIRED" olur ve yeni ters işlem yapılmaz.

Kurallar

  • Kapama, iptal ve kapamanın iptali yalnız ön provizyonun cihazında ve terminalinde yapılır (original_device_required, terminal_changed_since_original).
  • Satışa ön provizyon işlemi uygulanamaz: 409 physical_pos.payment.not_reversible (preauth_operation_on_sale).

Ters işlem yeni bir çocuk ödeme açar ve 202 döner (paymentStatus: "NOT_STARTED"). Sonucunu çocuk ödemenin webhook'uyla alırsınız (data.operation, data.rootPaymentId). Asıl ödeme için ayrı webhook gönderilmez; asıl ödemenin güncel reversalStatus değerini sorgulayarak okuyun.

Bütün ters işlem kuralları, cihaz ve banka seçimi ve hata sebepleri: Ters İşlem Kuralları. Bütün kodlar: Hata Kodları.