Fatura yaşam döngüsü
Bir fatura, oluşturulmasından kapanmasına veya süresinin dolmasına kadar bir yol izler. Bu bölüm, faturanın bulunabileceği durumları, aralarında nasıl geçiş yaptığını ve satıcının her adımda ne yapabileceğini anlatır.
Fatura durumları
| Durum | API değeri | Açıklama | Ödeme aramasına dahil mi |
|---|---|---|---|
| Ödenmedi (Unpaid) | unpaid | Fatura kesildi, ödeme süresi geçmedi, ödeme alınmadı | Evet |
| Ödendi (Paid) | paid | Bir ödeme bulundu ve faturayla eşleştirildi | Hayır |
| Süresi doldu (Expired) | expired | Ödeme süresi geçti, ödeme alınmadı | Evet, süre dolduktan sonra bir saat daha |
| İptal edildi (Canceled) | canceled | Fatura, satıcı tarafından manuel olarak veya API ile iptal edildi | Hayır |
Durum geçişleri
- Fatura oluşturma. Fatura hemen Ödenmedi durumunu alır.
- Ödenmedi → Ödendi. Tam fatura tutarında bir ödeme geldi veya satıcı bir ödemeyi manuel olarak eşleştirdi.
- Ödenmedi → Süresi doldu. Ödeme süresi, ödeme alınmadan geçti.
- Ödenmedi → İptal edildi. Satıcı faturayı iptal etti.
- Süresi doldu → Ödendi. Ödeme, süre dolduktan sonraki bir saat içinde geldi ve otomatik olarak bulundu ya da satıcı onu manuel olarak eşleştirdi.
- İptal edildi. Nihai bir durumdur; geri dönüş yoktur.
Ödendi durumundaki bir fatura da durum değiştirmez — yeniden ödenemez veya iptal edilemez.
Ödeme süresi
Süre, fatura oluşturulurken ayarlanır ve 30 dakika ile 12 saat arasındadır. İzin verilen değerler: 30 dakika, 1 saat, 3 saat, 6 saat, 12 saat.
Süre dolana kadar alıcı ödeme formunu görür ve faturayı ödeyebilir. Süre dolduktan sonra fatura Süresi doldu durumuna geçer ve ödeme formu artık ödeme önermez.
İki uç da bedelle gelir. Kısa süre, yavaş ağlarda risklidir — alıcı yetişemeyebilir. Uzun süre ise fatura oluşturulduğu andaki kur ile ödeme anındaki kur arasındaki farkı büyütür.
Ödeme arama penceresi
Ödeme araması, ödeme süresinden sonra bir saat daha devam eder — bu, işlemin faturanın süresi resmen dolduktan sonra onaylanabildiği yavaş ağlar içindir. Bu süre boyunca alıcı, faturayı süresi dolmuş olarak görür; ancak doğru tutarda bir ödeme geldiğinde fatura, tüm bildirimlerle birlikte otomatik olarak Ödendi durumuna geçer.
Buradan entegrasyoncular için kural çıkar: bir ödeme bildirimini süre geçti diye reddetmeyin — bu kontrol, gerçek ödemelerin bir bölümünü keser.
Faturayı iptal etme
Hata içeren bir faturayı iptal edebilirsiniz. İptal için iki koşul gerekir:
- Fatura ödenmemiş — yani Ödenmedi durumunda
- Faturanın ödeme sayfasını kimse açmamış; görüntülenme sayacı sıfır
İkinci koşul, alıcının zaten gördüğü ve belki de ödemeye başladığı bir faturanın iptaline karşı korur.
İptal geri alınamaz. İptal edilen fatura, ödeme aramasından çıkarılır ve ona manuel olarak bile ödeme eşleştirilemez. Ödeme olasıysa iptal etmek yerine sürenin dolmasını bekleyin — süresi dolmuş bir fatura yine de bir ödemeyle kapatılabilir.
Oluşturmada ne sabitlenir, ödemede ne yeniden hesaplanır
Fatura oluşturulurken hizmet, itibari tutarı güncel kurla kriptoya dönüştürür ve ortaya çıkan tutarları fatura için sabitler. Alıcının gördüğü tutarlar bunlardır ve hizmetin on-chain aradığı tutarlar da bunlardır. Kur artık bunları etkilemez: ne kadar zaman geçerse geçsin alıcı, tam olarak sabitlenen tutarı öder.
Ödeme anında muhasebe tutarları yeniden hesaplanır:
| Alan | Ne olur |
|---|---|
amountFiat | Faturanın itibari para cinsinden orijinal tutarı. Asla değişmez |
amountFiatUSD | Üzerine, fiilen alınan ve ödeme anındaki kurla USD'ye dönüştürülen tutar yazılır |
commissionFiatUSD | Yeni amountFiatUSD değerinden, projenin ücret oranıyla yeniden hesaplanır |
Kur hareketi nedeniyle bu değerler, ödeme tam olsa bile orijinallerinden farklı olabilir. Mağazanızdaki siparişle mutabakat için amountFiat değerini kullanın — değişmeden kalan tek tutar budur.
Faturanın ömrü boyunca bildirimler
Bildirimler proje bazında yapılandırılır. Bir faturanın iki bildirimi vardır:
- Gelen ödeme (Incoming payment). Cüzdanınızda herhangi bir gelen işlem algılandığında, bir faturayla eşleşip eşleşmediğine bakılmaksızın e-postaya ve Telegram'a gönderilir.
- Fatura ödendi (Invoice paid). Fatura Ödendi durumuna geçtiği anda e-postaya, Telegram'a ve Webhook URL'ye gönderilir — hem otomatik hem manuel eşleştirmede.
Bu, basit bir tanı kuralı verir: gelen ödeme bildirimi geldiyse ama ardından fatura ödendi bildirimi gelmediyse, ödeme tutar uyuşmazlığı nedeniyle eşleşmemiştir ve manuel işlem gerektirir.
Alıcıyı mağaza sitesine döndürme
Proje ayarlarında, alıcının ödeme sayfasından döneceği iki adres ayarlayabilirsiniz:
- Successful URL — fatura ödendikten sonra otomatik yönlendirme
- Unsuccessful URL — süresi dolmuş veya iptal edilmiş bir fatura açıldığında otomatik yönlendirme
Her adres ayrı ayrı etkinleştirilir. Adres ayarlanmamışsa alıcı, ödeme sayfasında kalır ve fatura durumunu görür.
Adrese uid parametresi — faturanın alıcıya yönelik tanımlayıcısı — eklenir: https://example.com/order/success?uid=AFhygKX21ecd. Mağaza bununla siparişi bulur ve alıcıya kendi sayfasını gösterir.
Bu adreslere gelinmesi ödemeyi onaylamaz — alıcı bağlantıyı elle de açabilir. Siparişleri webhook temelinde veya API üzerinden fatura durumunu kontrol ettikten sonra teslim edin.