İadeler

İade, çekilen parayı alıcının kartına geri döndürür. Tek çağrı iki durumu da karşılar: tutarı hiç göndermezseniz tam iade, amount geçerseniz kısmi iade — ve ödeme tamamen iade edilene kadar istediğiniz kadar kısmi iade yapabilirsiniz. Platform, ödeme başına kümülatif iade toplamını izler ve çekilenden fazlasını asla iade edememenizi garanti eder.

Tüm tutarlar minor-unit (kuruş) integer'dır: "amount": 2500 = ₺25,00 iade. Asla ondalık veya float göndermeyin.

⚠️

İade, çekilmiş para içindir. Ödeme henüz yalnızca AUTHORIZED durumundaysa (tutar bloke, çekilmemiş), bunun yerine void ile serbest bırakın — bu, karta para hareketi olmadan blokeyi kaldırır.

Nasıl çalışır

İade endpoint'ini çağırın

Step-Up kimlik bilgileriniz ve bir Idempotency-Key ile POST /payments/:id/refund. Kısmi iade için amount ekleyin; kalan iade edilebilir bakiyenin tamamı için hiç göndermeyin.

Platform doğrular ve yürütür

Ödemenin statüsü ve kümülatif iade sayacı kontrol edilir — ödeme iade edilebilir değilse veya tutar kalanı aşıyorsa istek reddedilir. İade, ardından orijinal çekimi işleyen sağlayıcıya iletilir.

Ödeme statüsü güncellenir

Kısmi iadeler ödemeyi PARTIALLY_REFUNDED durumuna taşır; kümülatif iade toplamı çekilen tutara ulaştığında REFUNDED olur.

Webhook teyit eder

payment.partially_refunded veya payment.refunded, webhook endpoint'inize teslim edilir. Sipariş durumunuzu yalnız senkron yanıttan değil, webhook'tan mutabık kılın.

İstek

Kimlik doğrulama Step-Up'tır: at_live_… Bearer token'ınız artı Ed25519 istek imzası — tüm para hareketi endpointlerinde zorunludur; bkz. Authentication.

Alan	Tip	Anlamı
`amount`	integer (minor unit), opsiyonel	İade edilecek tutar. Kalan iade edilebilir bakiyenin tam iadesi için göndermeyin.
`reason`	string, opsiyonel	Serbest metin sebep; raporlamanız için iade kaydında saklanır.

# ₺25,00 kısmi iade
curl https://api-gateway.lunixi.com/api/v1/payments/pay_01J9ZK3W8Q/refund \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Idempotency-Key: refund-order-84721-1" \
  -H "Content-Type: application/json" \
  # ...artı Ed25519 istek-imza header'ları — bkz. Authentication
  -d '{
    "amount": 2500,
    "reason": "Bir urun iade edildi"
  }'
 
# Tam iade — amount göndermeyin
curl https://api-gateway.lunixi.com/api/v1/payments/pay_01J9ZK3W8Q/refund \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Idempotency-Key: refund-order-84721-final" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Siparis iptal edildi" }'

Her iade niyeti için ayrı bir Idempotency-Key kullanın. Aynı key'le tekrar denemek aynı iadeyi güvenle geri oynatır (ağ zaman aşımları çifte iade yaratmaz); aynı ödemede yeni bir key, ek bir kısmi iade oluşturur.

Yanıt

{
  "paymentId": "pay_01J9ZK3W8Q",
  "status": "PARTIALLY_REFUNDED",
  "amount": 10050,
  "currency": "TRY"
}

Yanıttaki amount ödemenin çekilen tutarıdır (taksitte vade farkı dahil). Kümülatif iade tutarı çekilen tutara ulaştığında status, REFUNDED olur.

Tam vs kısmi — kümülatif sayaç

Her iade, ödemenin kalan iade edilebilir bakiyesine mahsup edilir:

Senaryo	Sonuç
`amount`'suz iade	Kalan bakiyenin tamamı iade edilir → `REFUNDED`
Kısmi `amount` < kalan	Ödeme → `PARTIALLY_REFUNDED`; sayaç artar
Toplamı çekilen tutara ulaşan birden çok kısmi iade	Sonuncusu ödemeyi `REFUNDED` durumuna çevirir
`amount` > kalan bakiye	Reddedilir — fazla iade imkânsızdır

Kısmen capture edilmiş bir ödemede (PARTIALLY_CAPTURED) iade tavanı, başlangıçta yetkilendirilen tutar değil, çekilen tutardır.

Hangi statuslarda iade mümkün

Ödeme statüsü	İade edilebilir mi?
`CAPTURED`, `SETTLED`, `PARTIALLY_CAPTURED`	Evet
`PARTIALLY_REFUNDED`	Evet — kalan bakiyeye kadar
`AUTHORIZED`	Hayır — blokeyi kaldırmak için void kullanın
`REFUNDED`	Hayır — iade edilecek bir şey kalmadı
`INITIATED`, `PROCESSING`, `AWAITING_3D`	Hayır — henüz çekilmiş para yok
`FAILED`, `VOIDED`, `EXPIRED`	Hayır — para hareketi olmadı
`CHARGEDBACK`	Hayır — chargeback yaşam döngüsü üzerinden yürütün

Parçalı ödeme. Checkout Formu'nda birden fazla kart ya da yöntemle ödenmiş siparişin ödeme kaydına gelen iade parçalara dağıtılır; bu iadede amount zorunludur ve parça parça sonuç meta.details.splitRefund alanında döner. Dağıtım kuralı ve API ile başlatılan parçalı ödemenin iade ucu: Parçalı Ödeme › İade.

Hatalar

Durum	Ne görürsünüz	Ne yapmalı
Ödeme iade edilebilir bir statüde değil	`409`	`GET /payments/:id` ile kontrol edin; `AUTHORIZED` ise void kullanın
`amount` kalan iade edilebilir bakiyeyi aşıyor	`422`	Ödemeyi okuyun, en fazla kalan bakiyeyi iade edin
Zaten tamamen iade edilmiş	`409`	Yapılacak bir şey yok — mutabakatta başarı sayın
Bilinmeyen payment id	`404`	`paymentId`'yi doğrulayın
Aynı `Idempotency-Key` ile tekrar istek	Aynı iade sonucu geri döner	Güvenli — çifte iade olmaz
Sağlayıcı tarafında iade hatası	Hata yanıtı; ödeme statüsü değişmez	Daha sonra aynı `Idempotency-Key` ile tekrar deneyin

Webhook'lar

Event	Ne zaman ateşlenir
`payment.partially_refunded`	Bir kısmi iade başarılı oldu; bakiye kaldı
`payment.refunded`	Ödeme artık tamamen iade edildi

Endpoint yapılandırması ve teslimat semantiği için Webhooks.

Sonraki adımlar

Ön Provizyon, Capture & İptal — çekilmemiş bir yetkilendirmeyi serbest bırakma
Ödemeleri Listeleme — bir ödemenin güncel statüsünü ve geçmişini okuma
Chargeback'ler — alıcı sizden iade istemek yerine itiraz ettiğinde

Taksit & BIN Cüzdana İade