Ön Provizyon
- 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ıcaDigest. 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 anahtar403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar403 API_INSUFFICIENT_SCOPEalı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ım | Uç | operation |
|---|---|---|
| Ön provizyon açma | POST /api/v1/physical-pos/payments | PREAUTH_OPEN |
| Kapama (tahsil) | POST /api/v1/physical-pos/payments/{paymentId}/reversals | PREAUTH_CLOSE |
| İptal (blokeyi kaldırma) | POST /api/v1/physical-pos/payments/{paymentId}/reversals | PREAUTH_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"); aksi409 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 tutarcapturedMinoralanı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:
VOIDile tahsil edilen tutarın tamamı geri alınır. → İptal (Void) - İade:
REFUNDile tahsil edilen tutardan en çokcapturedMinor − reversedMinorkadar 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ı.