İade
- 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 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
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
operation | string | Evet | REFUND. |
amountMinor | string | Evet | İade tutarı, en küçük birimde, dize. Tam iade için kalan iade edilebilir tutarın tamamı: asıl ödemenin approvedAmountMinor − reversedMinor değeri. |
currency | string | Evet | Satışın para birimi. |
target | object | null | Hayır | İadeyi başka bir cihazda yapmak için hedef cihaz. Gönderilmezse satışın cihazında yürür. → Cihaz ve banka |
merchantReference | string | null | Hayır | Kendi referansınız. |
startTimeoutSeconds | integer | Hayır | Cihazda 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ış (
APPROVEDya daPARTIALLY_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_progressalı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
REFUNDyapılır. Void422 physical_pos.payment.operation_unsupported(details.reason:device_direct_refund_only) alır. - İade yalnız satışın yapıldığı cihazda yürür.
targetile başka cihaz hedeflerseniz400 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 çoksa422 … device_sale_terminal_acquirer_ambiguous. Satışın banka bilgisi eksikse422 … original_terminal_acquirer_unknown. - İadenin webhook'larında
data.original.originDEVICE_DIRECTolur. → Webhook Olayları
Hatalar
| HTTP | code | Ne zaman |
|---|---|---|
400 | physical_pos.payment.refund_exceeds_remaining | Tutar kalan iade edilebilir tutarı aşıyor (details.remainingMinor, dize). |
400 | physical_pos.payment.amount_invalid | Tutar yok, 0 ya da biçim dışı. |
400 | physical_pos.payment.currency_mismatch | Para birimi satışınkinden farklı. |
409 | physical_pos.payment.not_reversible | root_not_approved, refund_after_final_reversal (satış void edilmiş ya da tamamen iade edilmiş). |
409 | physical_pos.payment.reversal_in_progress | Sonuçlanmamış ters işlem var. |
404 | physical_pos.payment.not_found | Satış yok. |
422 | physical_pos.payment.operation_unsupported | Banka 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ı.