Ters İşlem Kuralları
- 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.
Void, iade, kısmi ve kalem bazlı iade, ön provizyon kapama ve iptali aynı uçla yapılır. İşlem başına sayfalar: İptal (Void) · İade · Kısmi İade · Kalem Bazlı İade · Ön Provizyon. Bu sayfa ucun bütün kurallarını tek yerde toplar.
cURL örnekleri imzayı lunixi-sign.sh ile hesaplar: Kimlik Doğrulama › İmza yardımcısı.
Ödeme başlatma ve ters işlem, hedef cihazın modeli için ödeme yetenek tanımı bulunduğunda yürür. Yetenek tanımı bulunmayan cihazda istek, cihaz bulunduktan, terminal bağı ve haberleşme kanalı denetlendikten sonra 422 physical_pos.payment.operation_unsupported (details.reason: capability_undefined) alır; ödeme kaydı oluşmaz.
İstek
POST /api/v1/physical-pos/payments/{paymentId}/reversals · Idempotency-Key zorunlu
Bir ödemeyi geri alır ya da ön provizyonu kapatır. Yoldaki paymentId asıl ödemedir (kök); kök SALE ya da PREAUTH_OPEN olmalı ve APPROVED ya da PARTIALLY_APPROVED durumunda bulunmalıdır. Ters işlemin ters işlemi yapılmaz. Yanıttaki payment yeni açılan çocuk ödemedir: originalPaymentId ve rootPaymentId kökü gösterir.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
operation | string | Evet | VOID, REFUND, PREAUTH_CLOSE ya da PREAUTH_CANCEL. |
amountMinor | string | Koşullu | REFUND ve PREAUTH_CLOSE'da zorunlu, 0'dan büyük. Kalemli REFUND'da isteğe bağlıdır: tutar kalemlerden hesaplanır, gönderirseniz hesaplanan tutara eşit olmalıdır. VOID ve PREAUTH_CANCEL'de gönderilmez; tutarın tamamı uygulanır. |
currency | string | Evet | Kökün para birimi. |
merchantReference | string | null | Hayır | Ters işlem için kendi referansınız; ödeme başlatmadaki kuralla. Aynı referans denetimi ters işlemde yapılmaz. |
startTimeoutSeconds | integer | Hayır | Ödeme başlatmadaki gibi, 5–30 saniye. |
target | object | null | Hayır | Yalnız REFUND'da: iadeyi başka bir cihazda yapmak için hedef cihaz. Gönderilmezse ters işlem kökün cihazında yürür. Doğrudan cihazda yapılan satışın iadesi başka cihazda yapılmaz. → Cihaz ve banka |
items | array | Hayır | Yalnız REFUND'da: kalem bazlı iade satırları { lineNo, quantityMilli, amountMinor? }, en çok 500. Tutar bazlı iadede alanı göndermeyin; boş dizi reddedilir. → Kalem bazlı iade |
Gönderilen amountMinor kanonik pozitif minor-unit dize olmalıdır; açık null reddedilir. VOID ve PREAUTH_CANCEL için alanı göndermeyin. Kalemli REFUND işleminde alanın yokluğu toplamın kalemlerden hesaplanmasını sağlar; tutar bazlı REFUND ve PREAUTH_CLOSE işlemlerinde tutar hâlâ zorunludur.
Hangi ters işlem ne zaman yapılır
settledAt dolu) void yapılamaz. Kısmi ve kalem bazlı iade cihaz modelinin desteğini ister.| İşlem | Kök | Tutar | Ne zaman |
|---|---|---|---|
VOID | SALE | Onaylanan tutarın tamamı | Kökte hiç ters işlem yokken (reversalStatus: "NONE") ve gün sonundan önce. Doğrudan cihazda yapılan satışta void yapılmaz. |
VOID | PREAUTH_OPEN | Kapanan tutarın tamamı | Ön provizyon kapandıktan sonra (PREAUTH_CLOSED): kapamanın iptali. |
REFUND | SALE | En çok: onaylanan − iade edilen − kapanan | NONE ya da PARTIALLY_REFUNDED; birden çok kısmi iade yapılabilir. |
REFUND | PREAUTH_OPEN | En çok: kapanan − iade edilen | PREAUTH_CLOSED ya da PARTIALLY_REFUNDED. |
PREAUTH_CLOSE | PREAUTH_OPEN | Onaylanan tutar artı cihaz modelinin izin verdiği pay | Açık ön provizyonda (NONE). |
PREAUTH_CANCEL | PREAUTH_OPEN | Açık tutarın tamamı | Açık ön provizyonda (NONE). |
- Cihaz modelinin desteği: kısmi iade (onaylanan tutarın tamamından az ya da daha önce iade yapılmış satışta yeni iade, yani birden çok iade), kısmi ön provizyon kapama (açık tutardan az) ve kalem bazlı iade, cihaz modelinin bu işlemleri desteklemesini gerektirir. Desteklenmiyorsa istek
422 physical_pos.payment.operation_unsupportedalır:details.reasonpartial_amount_unsupportedya daitemized_unsupported. Void, ön provizyon iptali ve tutarın tamamı için tek iade bu kısıta girmez. - Tek bekleyen ters işlem: kökte sonuçlanmamış bir ters işlem varken yenisi
409 physical_pos.payment.reversal_in_progressalır. Bekleyen ters işlem kökünpendingReversalIdalanındadır. - Bekleyen ters işlemin tutarı kökte ayrılır (
reversalReservedMinor). ÇocukAPPROVEDolunca tutar kesinleşir;DECLINED,CANCELLED,EXPIREDya daFAILEDolunca ayrılan tutar serbest kalır. ÇocukUNKNOWNya daMANUAL_REVIEWiken ayrılan tutar korunur; bu, aynı tutarın iki kez iade edilmesini önler. - Kısmi onaylanan (
PARTIALLY_APPROVED) ödemede tavanların tabanı onaylanan tutardır. - Gün sonu: gün sonu kapanmış ödemeye void
409 physical_pos.payment.void_after_settlementalır (details.allowedOperation:REFUND); tutarı aynı ödemeyeREFUNDile geri ödeyin. Kural cihaz modelinden bağımsızdır. → Gün sonu ve void
Cihaz ve banka
- Void ve ön provizyon işlemleri yalnız kökün cihazında ve terminalinde yapılır. Başka cihaz hedeflerseniz
400 physical_pos.payment.target_invalid(details.reason:original_device_required). Kökün cihazı o arada başka bir terminale bağlandıysa409 physical_pos.payment.terminal_not_payable(details.reason:terminal_changed_since_original). - İade organizasyonunuzun başka bir cihazından da yapılabilir ve satışın bankasına gider:
- Aynı terminalde iade satışın banka satırıyla yürür; satır sonradan devre dışı bırakılmış olsa bile kullanılır.
- Başka terminalde, o terminalin satışla aynı bankaya ve aynı üye işyeri numarasına sahip, etkin, eşlenmiş ve para birimini taşıyan tek banka satırı kullanılır. Böyle satır yoksa
422 … refund_terminal_acquirer_not_on_device, birden çoksa422 … refund_terminal_acquirer_ambiguous. - Satışta banka satırı seçilmediyse (
terminalAcquirerId: null) iade başka terminalde yapılamaz:422 … original_terminal_acquirer_unknown. Aynı terminalde yapılabilir.
- Doğrudan cihazda yapılan satışın iadesi yalnız satışın cihazında yapılır. → Cihazda doğrudan satışın iadesi
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"Tutar bazlı kısmi iade gövdesi (cihaz modeli kısmi iadeyi destekliyorsa): {"operation":"REFUND","amountMinor":"1500","currency":"TRY"}. Kalem bazlı iade: Kalemler › Kalem bazlı iade.
Yeni ters işlemde 202, tekrarda 200 döner; data: { "payment": { … }, "replayed": false }. Çocuk ödeme operation: "VOID", paymentStatus: "NOT_STARTED" ile başlar.
Hatalar (ödeme başlatmadakilere ek olarak):
| HTTP | code | Ne zaman |
|---|---|---|
404 | physical_pos.payment.not_found | Kök ödeme yok. |
400 | physical_pos.payment.amount_invalid | details.reason: not_positive (0 ya da negatif), full_amount_operation (VOID / PREAUTH_CANCEL'de tutar), preauth_close_exceeds_tolerance, item_amount_mismatch (kalemlerden hesaplanan tutar farklı; details.expectedMinor). |
400 | physical_pos.payment.refund_exceeds_remaining | İade, iade edilebilir kalan tutarı aşıyor (details.remainingMinor, dize). |
400 | physical_pos.payment.currency_mismatch | Para birimi kökünkinden farklı. |
400 | physical_pos.payment.refund_items_invalid | İade kalemlerinden biri geçersiz. → Kalem bazlı iade |
409 | physical_pos.payment.not_reversible | Bu ters işlem bu kökte yapılamaz (aşağıya bakın). |
409 | physical_pos.payment.void_after_settlement | Gün sonu kapanmış ödemeye void; details.allowedOperation: REFUND. İade yapın. |
409 | physical_pos.payment.reversal_in_progress | Kökte sonuçlanmamış ters işlem var. |
409 | physical_pos.payment.terminal_not_payable | terminal_changed_since_original ya da terminal hazır değil. |
422 | physical_pos.payment.operation_unsupported | operation_not_reversal, kalem bazlı iade ya da banka satırı sebepleri (aşağıya bakın). |
physical_pos.payment.not_reversible için details.reason:
details.reason | Anlamı |
|---|---|
root_operation | Kök SALE ya da PREAUTH_OPEN değil. |
root_not_approved | Kök onaylanmamış (sonucu belirsiz olanlar dahil). |
void_after_reversal | Kökte daha önce ters işlem yapılmış; void yapılamaz. |
void_preauth_not_closed | Ön provizyon kapanmadan void yapılamaz. |
refund_after_final_reversal | Kök void edilmiş, tamamen iade edilmiş ya da ön provizyonu iptal edilmiş. |
refund_preauth_not_closed | Kapanmamış ön provizyon iade edilemez; iptal edin. |
preauth_operation_on_sale | Ön provizyon işlemi satışa uygulanamaz. |
preauth_not_open | Ön provizyon açık değil. |
Ters işlemde physical_pos.payment.operation_unsupported için ek details.reason değerleri:
details.reason | Anlamı |
|---|---|
operation_not_reversal | operation bu uçta kullanılamaz. |
item_refund_root_without_items | Kalemsiz satışta kalem bazlı iade. |
item_refund_root_not_sale | Kalem bazlı iade yalnız satışta yapılır. |
item_refund_partially_approved | Kısmi onaylanan satışta kalem bazlı iade yapılmaz; tutar bazlı iade yapın. |
partial_amount_unsupported | Cihaz modeli kısmi tutarlı iadeyi ya da kısmi ön provizyon kapamayı desteklemiyor. Tutarın tamamını kullanın. |
itemized_unsupported | Cihaz modeli kalem bazlı iadeyi desteklemiyor. Tutar bazlı iade yapın. |
original_reference_invalid | Asıl işlemin banka referansı cihaza iletilebilecek biçimde değil (details.field). |
original_terminal_closed | Satışın terminali kapatılmış. |
original_terminal_acquirer_unknown | Satışın banka satırı belli değil. |
original_terminal_acquirer_missing · original_terminal_acquirer_unmapped | Satışın banka satırı artık yok ya da eşlemesi bozulmuş. |
refund_terminal_acquirer_not_on_device · refund_terminal_acquirer_ambiguous | Hedef cihazın terminalinde uygun banka satırı yok ya da birden çok. |
device_direct_refund_only | Doğrudan cihazda yapılan satışta yalnız iade yapılır. |
device_sale_terminal_acquirer_not_found · device_sale_terminal_acquirer_ambiguous | Cihazın terminalinde satışın bankası ve TID'si ile eşleşen banka satırı yok ya da birden çok. |
Cihaz asıl işlemi bulamazsa çocuk ödeme FAILED olur (statusReason: DEVICE_REJECTED_ORIGINAL_NOT_FOUND) ve kökte ayrılan tutar serbest kalır.