Fiziksel POS
Ödeme İşlemleri
İade

İade

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.

Onaylanmış bir satışın tutarını müşterinin kartına geri ödersiniz. Gün sonu alınmış satış yalnız iadeyle geri alınır. Bu sayfa tutarın tamamının iadesini anlatır; bir kısmı için Kısmi İade, belirli ürün satırları için Kalem Bazlı İade.

POST /api/v1/physical-pos/payments/{paymentId}/reversals · physical_pos:payments · Idempotency-Key zorunlu

İstek

AlanTipZorunluAçıklama
operationstringEvetREFUND.
amountMinorstringEvetİade tutarı, en küçük birimde, dize. Tam iade için kalan iade edilebilir tutarın tamamı: asıl ödemenin approvedAmountMinor − reversedMinor değeri.
currencystringEvetSatışın para birimi.
targetobject | nullHayırİadeyi başka bir cihazda yapmak için hedef cihaz. Gönderilmezse satışın cihazında yürür. → Cihaz ve banka
merchantReferencestring | nullHayırKendi referansınız.
startTimeoutSecondsintegerHayırCihazda başlaması için süre, 5–30 saniye.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"REFUND","amountMinor":"4500","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: 8b4e2c71-5d3a-4f60-9a12-6c7d8e9f0a1b" \
  --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. Tam iade onaylanınca asıl ödemede reversalStatus: "REFUNDED" olur ve bu ödemeye başka ters işlem yapılmaz.

Kurallar

  • Satış onaylanmış (APPROVED ya da PARTIALLY_APPROVED) olmalıdır. Kısmi onaylanan satışta üst sınır onaylanan tutardır.
  • Satışta aynı anda tek bir sonuçlanmamış ters işlem olabilir; yenisi 409 physical_pos.payment.reversal_in_progress alır.
  • İade organizasyonunuzun başka bir cihazından da yapılabilir ve satışın bankasına gider; banka satırı seçimi: Cihaz ve banka.
  • Tutarın tamamının tek seferde iadesi cihaz modelinin kısmi iade desteğini gerektirmez.

Cihazda doğrudan satışın iadesi

Doğrudan cihazda yapılan satışı (origin: "DEVICE_DIRECT") bu uçla iade edersiniz. Yoldaki paymentId, satışın kimliğidir (physical_pos.payment.device_sale olayının data.paymentId değeri).

  • Yalnız REFUND yapılır. Void 422 physical_pos.payment.operation_unsupported (details.reason: device_direct_refund_only) alır.
  • İade yalnız satışın yapıldığı cihazda yürür. target ile başka cihaz hedeflerseniz 400 physical_pos.payment.target_invalid (details.reason: original_device_required).
  • Cihaz ödemeye hazır olmalıdır; değilse 409 physical_pos.payment.device_offline. İade kuyruğa alınmaz. → Cihazın ödemeye hazır olması
  • Kısmi ve kalem bazlı iade, diğer satışlardaki gibi cihaz modelinin desteğine bağlıdır (partial_amount_unsupported, itemized_unsupported). Tavanlar, tek bekleyen ters işlem kuralı ve sonucu belirsiz iadenin akışı diğer satışlardakiyle aynıdır.
  • İade satışın bankasına gider: cihazın bağlı olduğu terminalde satışın bankasını ve banka terminal numarasını (TID) taşıyan tek banka satırı kullanılır; satır sonradan devre dışı bırakılmış olsa bile kullanılır. Böyle satır yoksa 422 … device_sale_terminal_acquirer_not_found, birden çoksa 422 … device_sale_terminal_acquirer_ambiguous. Satışın banka bilgisi eksikse 422 … original_terminal_acquirer_unknown.
  • İadenin webhook'larında data.original.origin DEVICE_DIRECT olur. → Webhook Olayları

Hatalar

HTTPcodeNe zaman
400physical_pos.payment.refund_exceeds_remainingTutar kalan iade edilebilir tutarı aşıyor (details.remainingMinor, dize).
400physical_pos.payment.amount_invalidTutar yok, 0 ya da biçim dışı.
400physical_pos.payment.currency_mismatchPara birimi satışınkinden farklı.
409physical_pos.payment.not_reversibleroot_not_approved, refund_after_final_reversal (satış void edilmiş ya da tamamen iade edilmiş).
409physical_pos.payment.reversal_in_progressSonuçlanmamış ters işlem var.
404physical_pos.payment.not_foundSatış yok.
422physical_pos.payment.operation_unsupportedBanka satırı sebepleri (refund_terminal_acquirer_not_on_device, refund_terminal_acquirer_ambiguous, original_terminal_acquirer_unknown …).

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