Fiziksel POS
Ödeme İşlemleri
Ters İşlem Kuralları

Ters İşlem Kuralları

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.

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.

AlanTipZorunluAçıklama
operationstringEvetVOID, REFUND, PREAUTH_CLOSE ya da PREAUTH_CANCEL.
amountMinorstringKoşulluREFUND 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.
currencystringEvetKökün para birimi.
merchantReferencestring | nullHayırTers işlem için kendi referansınız; ödeme başlatmadaki kuralla. Aynı referans denetimi ters işlemde yapılmaz.
startTimeoutSecondsintegerHayırÖdeme başlatmadaki gibi, 5–30 saniye.
targetobject | nullHayırYalnı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
itemsarrayHayırYalnı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

İptal mi, iade mi?Onaylanmış satış gün sonundan önce ve tamamıyla geri alınacaksa void yapılır; değilse tutarın tamamı iade edilir, ürün satırlarına göre kalem bazlı iade ya da tutara göre kısmi iade yapılır; cihaza ulaşmamış ödeme başlamadan iptal edilir.EVETEVETEVETHAYIRHAYIRHAYIROnaylanmış satışı geri alGün sonundan önceve tamamı mı?Tamamı mı?Ürün satırlarınagöre mi?İptal (Void)operation: VOIDİadeREFUND · tam tutarKalem bazlı iadeREFUND + itemsKısmi iadeREFUND + amountMinorCihaza ulaşmadıysaBaşlamadan iptalLEJANTSORUVOIDİADEBAŞLAMADI
Gün sonu alındıysa (settledAt dolu) void yapılamaz. Kısmi ve kalem bazlı iade cihaz modelinin desteğini ister.
İşlemKökTutarNe zaman
VOIDSALEOnaylanan 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.
VOIDPREAUTH_OPENKapanan tutarın tamamıÖn provizyon kapandıktan sonra (PREAUTH_CLOSED): kapamanın iptali.
REFUNDSALEEn çok: onaylanan − iade edilen − kapananNONE ya da PARTIALLY_REFUNDED; birden çok kısmi iade yapılabilir.
REFUNDPREAUTH_OPENEn çok: kapanan − iade edilenPREAUTH_CLOSED ya da PARTIALLY_REFUNDED.
PREAUTH_CLOSEPREAUTH_OPENOnaylanan tutar artı cihaz modelinin izin verdiği payAçık ön provizyonda (NONE).
PREAUTH_CANCELPREAUTH_OPENAçı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_unsupported alır: details.reason partial_amount_unsupported ya da itemized_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_progress alır. Bekleyen ters işlem kökün pendingReversalId alanındadır.
  • Bekleyen ters işlemin tutarı kökte ayrılır (reversalReservedMinor). Çocuk APPROVED olunca tutar kesinleşir; DECLINED, CANCELLED, EXPIRED ya da FAILED olunca ayrılan tutar serbest kalır. Çocuk UNKNOWN ya da MANUAL_REVIEW iken 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_settlement alır (details.allowedOperation: REFUND); tutarı aynı ödemeye REFUND ile 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ıysa 409 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 çoksa 422 … 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):

HTTPcodeNe zaman
404physical_pos.payment.not_foundKök ödeme yok.
400physical_pos.payment.amount_invaliddetails.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).
400physical_pos.payment.refund_exceeds_remainingİade, iade edilebilir kalan tutarı aşıyor (details.remainingMinor, dize).
400physical_pos.payment.currency_mismatchPara birimi kökünkinden farklı.
400physical_pos.payment.refund_items_invalidİade kalemlerinden biri geçersiz. → Kalem bazlı iade
409physical_pos.payment.not_reversibleBu ters işlem bu kökte yapılamaz (aşağıya bakın).
409physical_pos.payment.void_after_settlementGün sonu kapanmış ödemeye void; details.allowedOperation: REFUND. İade yapın.
409physical_pos.payment.reversal_in_progressKökte sonuçlanmamış ters işlem var.
409physical_pos.payment.terminal_not_payableterminal_changed_since_original ya da terminal hazır değil.
422physical_pos.payment.operation_unsupportedoperation_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.reasonAnlamı
root_operationKök SALE ya da PREAUTH_OPEN değil.
root_not_approvedKök onaylanmamış (sonucu belirsiz olanlar dahil).
void_after_reversalKökte daha önce ters işlem yapılmış; void yapılamaz.
void_preauth_not_closedÖn provizyon kapanmadan void yapılamaz.
refund_after_final_reversalKök void edilmiş, tamamen iade edilmiş ya da ön provizyonu iptal edilmiş.
refund_preauth_not_closedKapanmamış ö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.reasonAnlamı
operation_not_reversaloperation bu uçta kullanılamaz.
item_refund_root_without_itemsKalemsiz satışta kalem bazlı iade.
item_refund_root_not_saleKalem bazlı iade yalnız satışta yapılır.
item_refund_partially_approvedKısmi onaylanan satışta kalem bazlı iade yapılmaz; tutar bazlı iade yapın.
partial_amount_unsupportedCihaz modeli kısmi tutarlı iadeyi ya da kısmi ön provizyon kapamayı desteklemiyor. Tutarın tamamını kullanın.
itemized_unsupportedCihaz modeli kalem bazlı iadeyi desteklemiyor. Tutar bazlı iade yapın.
original_reference_invalidAsıl işlemin banka referansı cihaza iletilebilecek biçimde değil (details.field).
original_terminal_closedSatışın terminali kapatılmış.
original_terminal_acquirer_unknownSatışın banka satırı belli değil.
original_terminal_acquirer_missing · original_terminal_acquirer_unmappedSatışın banka satırı artık yok ya da eşlemesi bozulmuş.
refund_terminal_acquirer_not_on_device · refund_terminal_acquirer_ambiguousHedef cihazın terminalinde uygun banka satırı yok ya da birden çok.
device_direct_refund_onlyDoğrudan cihazda yapılan satışta yalnız iade yapılır.
device_sale_terminal_acquirer_not_found · device_sale_terminal_acquirer_ambiguousCihazı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.