İptal (Void)
- 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.
Onaylanmış bir satışın tamamını, gün sonundan önce iptal edersiniz. Gün sonu alınmış satış void edilemez; onu iade ile geri alırsınız.
POST /api/v1/physical-pos/payments/{paymentId}/reversals · physical_pos:payments · Idempotency-Key zorunlu
Ne zaman void, ne zaman iade?
settledAt dolu) void yapılamaz. Kısmi ve kalem bazlı iade cihaz modelinin desteğini ister.| Durum | Yapılacak |
|---|---|
Satış onaylandı, gün sonu alınmadı (settledAt: null), hiç ters işlem yok | Void (bu sayfa) |
Gün sonu alındı (settledAt dolu) | İade |
| Tutarın bir kısmını geri vermek istiyorsunuz | Kısmi İade |
| Ödeme cihaza henüz ulaşmadı | Başlamadan İptal |
İstek
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
operation | string | Evet | VOID. |
currency | string | Evet | Satışın para birimi. |
merchantReference | string | null | Hayır | Kendi referansınız. |
startTimeoutSeconds | integer | Hayır | Cihazda başlaması için süre, 5–30 saniye. |
amountMinor göndermeyin: void her zaman onaylanan tutarın tamamıdır. Gönderirseniz 400 physical_pos.payment.amount_invalid (details.reason: full_amount_operation).
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"VOID","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: 3d2a9f10-6b1e-4c7a-8e55-0f1d2c3b4a59" \
--data-raw "$BODY"Sonuç
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. Void onaylanınca asıl ödemede reversalStatus: "VOIDED" olur ve bu ödemeye başka ters işlem yapılmaz.
Kurallar
- Void yalnız satışın cihazında ve terminalinde yapılır. Başka cihaz hedeflerseniz
400 physical_pos.payment.target_invalid(details.reason:original_device_required); cihaz o arada başka terminale bağlandıysa409 physical_pos.payment.terminal_not_payable(terminal_changed_since_original). - Cihaz ödemeye hazır olmalıdır; değilse
409 physical_pos.payment.device_offline. - Doğrudan cihazda yapılan satışta (
origin: "DEVICE_DIRECT") void yapılmaz; iade yapın. - Ön provizyon kapamasının iptali de
VOIDile yapılır: Ön Provizyon.
Hatalar
| HTTP | code | Ne zaman |
|---|---|---|
409 | physical_pos.payment.void_after_settlement | Gün sonu alınmış; details.allowedOperation: REFUND. Aynı ödemeye yeni bir Idempotency-Key ile iade yapın. |
409 | physical_pos.payment.not_reversible | void_after_reversal (önce ters işlem yapılmış), root_not_approved (satış onaylanmamış ya da sonucu belirsiz), void_preauth_not_closed. |
409 | physical_pos.payment.reversal_in_progress | Satışta sonuçlanmamış bir ters işlem var (pendingReversalId). |
400 | physical_pos.payment.amount_invalid | full_amount_operation: void'de tutar gönderildi. |
400 | physical_pos.payment.target_invalid | original_device_required. |
404 | physical_pos.payment.not_found | Satış yok. |
422 | physical_pos.payment.operation_unsupported | device_direct_refund_only ya da cihaz modeli void'i desteklemiyor. |
Bütün ters işlem kuralları, cihaz ve banka seçimi ve hata sebepleri: Ters İşlem Kuralları. Bütün kodlar: Hata Kodları.