İadeler

Bir Refund, Order üzerindeki bir bayrak değil, birinci sınıf bir varlıktır. Kısmi iadeler verebilir, aynı Order’a karşı birden fazla iade yapabilir veya aynı akışta iade + yeniden tahsilat gerçekleştirebilirsiniz.

İade kaydının var olabileceği iki yol:

Müşteri tarafından başlatılan akış, kısa ömürlü bir iade-talep token kullanır. Bir token üretirsiniz (B2B veya panel), URL’yi alıcıya nasıl isterseniz iletirsiniz ve alıcı iade detaylarını checkout.infraio.xyz/refund-request/:token üzerinde tamamlar. Alıcı asla API’nize dokunmaz ve satıcı anahtarınızı asla görmez.

İade yaşam döngüsü

Satıcı tarafından başlatılan

İade etmeye karar verirsiniz (örn. alıcı sohbet üzerinden şikayet etti). Satıcı-tarafından-başlatılan uç noktayı çağırın — incelemeyi atlar ve hemen APPROVED durumuna geçer.

POST /b2b/v1/merchants/{merchant_id}/refunds
{
  "order_id": "ord_01J5K…",
  "amount": "49.00",                       // kısmi veya tam, siparişin gösterim para biriminde
  "reason": "customer complaint #4521",
  "refund_to_address":   "0xBUYER…",       // kripto raylar için gereklidir
  "refund_network":      "polygon",        // network slug; bkz. Kavramlar → Zincirler
  "refund_token_address":"0xUSDC_CONTRACT" // geri ödenen ERC-20 sözleşmesi; genellikle orijinal token
}

İade isteğinde currency alanı yoktur — iadeler her zaman siparişin gösterim para birimini miras alır (bugün USD). (refund_to_address, refund_network, refund_token_address) üçlüsü zincir üstü hedeftir. Fiat raylar için yok sayılırlar (provider tarafından otomatik yönlendirilir).

Sipariş, zincir üstü transferi yürütene kadar mevcut durumunu korur (bkz. Bir kripto iadesini yürütme).

Müşteri tarafından başlatılan — iade-talep token’ları

Alıcı iade formunu bizim barındırılan sayfamızda doldurur, sizinkinde değil. Tek işiniz bir token üretmek ve URL’yi iletmek.

Token yaşam döngüsü

TTL varsayılanları

Varsayılanı ttl_seconds gövde alanıyla geçersiz kılabilirsiniz. Minimum veya maksimum sınır uygulanmaz; yaygın değerler 1 dakika ile 7 gün arasındadır.

B2B API üzerinden üretim

Bir destek konuşmasından hemen sonra, sipariş iptal akışından vb. programatik olarak bir iade bağlantısı üretmek isteyen backend’ler için.

POST /b2b/v1/merchants/{merchant_id}/refund-requests
Content-Type: application/json
X-Client-ID: pk_live_…
X-Timestamp: 1729536000
X-Signature: 4f2a1b9c8d3e2f1a0b9c8d7e6f5a4b3c…
 
{
  "ref_type":    "order_id",                          // gerekli: order_id | order_number | session_id | session_key
  "ref_value":   "ord_01J5K…",                        // gerekli: ref_type ile eşleşir
  "amount":      "49.00",                             // gerekli — alıcının gönderebileceği maksimumu kilitler
  "ttl_seconds": 1800,                                // opsiyonel — varsayılan 1800 (30 dk)
  "metadata":    { "support_ticket": "4521" },        // opsiyonel — Stripe stili anahtar/değer
  "hide_summary": false,                              // barındırılan form için opsiyonel UI bayrakları
  "hide_header":  false
}

Tutar üretim gövdesinde vardır ve gereklidir. Alıcının form üzerinde gönderebileceği tavanı kilitler — daha azı için gönderebilirler ama asla daha fazlası için değil. (Kısmi iadeler için kısmi tutarla bir token üretin; tam iadeler için sipariş toplamı ile üretin.)

Eski { "order_id": "..." } şekli hâlâ kabul edilir ve ref_type=order_id olarak değerlendirilir, ancak yeni entegrasyonlar açık ref_type + ref_value çiftini kullanmalıdır.

Yanıt:

{
  "token":      "rfqt_01J7P3Q9R…",
  "refund_url": "https://checkout.infraio.xyz/refund-request/rfqt_01J7P3Q9R…",
  "expires_at": "2026-05-28T10:32:00Z"
}

Webhook uç noktalarınıza refund_request.created tetikler (böylece bir sipariş için hangi token’ın şu anda aktif olduğunu loglayabilir / denetim yapabilirsiniz).

Panel üzerinden üretim

Satıcı panelindeki  Issue Refund modal’ı bir geçiş anahtarı sunar: Şimdi yürüt vs Müşteriye bağlantı gönder. İkincisini seçmek bir iade-talep token’ı oluşturur (yukarıdaki B2B çağrısıyla aynı) ve size URL’yi bir kopyalama butonu ve QR kodu ile gösterir. Hangi kanal mantıklıysa yapıştırın — e-posta, destek sohbeti, SMS.

JavaScript SDK üzerinden — openRefundRequest

Yığınınızda zaten @lartech/infraio-checkout-js varsa ve alıcının iadeyi harici bir URL aracılığıyla değil, kendi sayfa akışınızın içinde tamamlamasını istiyorsanız, B2B üretimini sdk.openRefundRequest() ile eşleyin:

// Sunucu tarafı: token'ı üret
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
// İstemci tarafı: barındırılan formu aç
const sdk = await loadInfraIo("pk_live_yourkeyhere");
const close = sdk.openRefundRequest({
  token,
  mode: "popup",                       // veya "redirect" | "embed"
  onSuccess: ({ linkToken, refundId }) => {
    // linkToken → /r/:linkToken alıcı durum sayfası.
    // refundId  → approve / reject için B2B API referansı.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* alıcı popup'ı kapattı */ },
  onError:  (err) => { /* bkz. SDK referansı */ },
});

Tam seçenek tablosu için SDK referansı → sdk.openRefundRequest() sayfasına bakın.

Müşteri yenilemesi — alıcı tarafından yönlendirilen yeniden-üretme

Alıcı URL’yi token süresi dolduktan sonra açarsa, sayfa formun yerine bir Yeni bağlantı talep et butonu sunar. Tıklamak:

1. Yenileme talebini gönderir (kimlik bilgisi gerekmez; bağlantının kendisi yetkilendirir)
2. Opsiyonel olarak alıcının sizin için bırakabileceği bir serbest metin not (customer_note) yakalar
3. Token’ı RENEWAL_REQUESTED’a geçirir ve webhook’unuza refund_request.renewal_requested tetikler

Paneliniz yenileme-talepleri widget’ında bir rozet gösterir. Onaylayın (tek tık) ve yeni bir ACTIVE token verilir, refund_request.renewed tetiklenir ve yeniden göndermek için yeni URL’yi kopyalamanıza izin verir. Eski URL erişilebilir kalır ama “Değiştirildi — e-postanıza bakın” gösterir, böylece eski URL’nin yönlendirilmiş bir kopyası yeniyi çekmek için kullanılamaz.

Bir kripto iadesini yürütme

API niyeti kaydeder — fonları hareket ettirmez. Siz satıcı cüzdanınızdan zincir üstü transferi imzalar ve yayar, ardından tx hash’i iade kaydına damgalarsınız:

POST /b2b/v1/refunds/:refund_id/submit-tx
Content-Type: application/json
 
{
  "tx_hash": "0xabcd…",
  "network": "ethereum",
  "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

Üç gövde alanının da olması gereklidir: aynı tx hash farklı zincirlerde var olabilir ve orijinal ödemenin tahsil edildiği stablecoin’den farklı bir stablecoin’de iade yapabilirsiniz.

InfraIO Pay, bu işlemin gerekli onay sayısına ulaştığını gördüğünde (bkz. Zincirler ve varlıklar), iade EXECUTED durumuna geçer ve Order’ın iade-toplamı güncellenir.

TRON, Solana ve TON’da iadeler

Akış aynıdır: iadeyi kendi cüzdanınızdan gönderir, ardından işlem hash’ini iletirsiniz. Ayrıntılar ağa göre değişir:

• Panelde iade ekranı hedefi, tutarı, ağı ve tokeni gösterir; ağ destekliyorsa bir QR kodu da sunar: Solana’da Solana Pay QR’ı, TON’da bir TON transfer bağlantısı. TRON’da kopyalanacak hedef adresi gösterir (hiçbir cüzdan bağlantısı tutarı taşımaz), bu yüzden tutarı kendiniz girin.
• token_address, o ağdaki tokenin adresidir: TRC-20 kontratı, SPL mint’i veya Jetton master adresi.
• İşlem hash biçimleri farklıdır: TRON’da öneksiz hex, Solana’da base58 imza, TON’da hex veya base64 hash.
• Platform tam olarak bu işlemi zincir üstünde doğrular, ardından Zincirler ve varlıklar sayfasındaki onay sayılarını kullanarak iadeyi EXECUTED durumuna geçirir.

Webhook event’leri

İade alt sistemi iki event ailesini tetikler:

Token yaşam döngüsü (refund_request.*)

İade yaşam döngüsü (payment.refund.*)

payment.failed bir iade için tetiklenmez — iadeler kendi event serisine sahiptir, payment.refund.* öneki altında.

Sırada ne var

• SDK referansı → sdk.openRefundRequest() — barındırılan iade formunu popup / yönlendirme / gömme olarak açın.
• API referansı → İadeler — uç nokta kataloğu (üret, gönder, yenile, durum).
• Kavramlar → Siparişler — Refund durumunun Order yaşam döngüsüne nasıl bağlandığı.
• Webhook’lar → Genel bakış — tam event kataloğu.