Müşteri yanlış tutarı gönderirse ne olur?

Fatura 200 USDT istedi, adrese 198,5 USDT düştü. Kimse hata yapmadı: transfer onaylı, zincirde geri çevirme diye bir şey yok ve eksik kalan kısım tam olarak müşterinin borsasının kestiği ücret kadar.

Kartla çalışan satıcı için bu yeni bir kategori. Orada tutar ya tam geçer ya hiç geçmez; sipariş listesinde "eksik ödendi" diye bir satır bulunmaz. Kripto tarafında iki yön de açık — az gelen para da, fazla gelen para da — ve hangisinin ne yapacağı ödeyen kişi sayfayı açmadan çok önce, fatura oluşturulurken belli oluyor. Üçüncü bir vaka daha var ve onu bu ikisinden ayrı tutmak gerekiyor: adrese ulaşıp faturayı hiç ödemeyen para. Onun ne durumu ne de olayı var, yalnızca bakiyede bir satırı.

Faturayı kurma tarafı ayrı bir rehbere ait, bütün geçişleri taşıyan durum tablosu da ödeme akışında duruyor; buradaki soru tutarın kendisi. Her sonucun üç karşılığı var: bakiyenizde, siparişinizde ve sunucunuza düşen olayda.

Fazla gelen tutar nereye gider?

Bakiyeye — tamamı.

Fazlası alıkonmaz, kendiliğinden geri gönderilmez, ödeme başarısız da sayılmaz; fatura ödendi olarak kapanır. İşlem komisyonu da faturanın istediği tutardan değil, onaylanan transferlerin toplamından alınır — yükteki payment.fee, payment.paid üzerinden hesaplanır. Oranın kendisi fiyat sayfasında.

İki durumu ayıran şey olay adı. Tam tutarı karşılayan ödeme invoice.paid yayar; üzerine çıkan ödeme invoice.paid_over yayar ve sisteminizin eline verilen tek fark bu addır.

Fazlayı iade etmek sizin kendi transferiniz. Kendiliğinden hiçbir şey çıkmaz ve karar teknik değil ticari: yuvarlama kuyruğu bir işleme değmez, fazladan sıfır yazmış müşteri ise siz fark etmeden size yazar.

Fatura ödendi, sipariş neden çıkmadı?

Çünkü işleyici tek bir metne bakıyor.

Olay size ulaşıyor. Abonelik kategori düzeyinde alınır ve kategorinin içindeki adlar tek tek seçilemez, dolayısıyla fatura kategorisini alan uç nokta sekiz olayın hepsini alır — invoice.paid_over dahil. Teslimat düşer, işleyici event_type alanını invoice.paid ile karşılaştırır, tutmadığını görür ve olayı ilgilenmediklerinin arasına atar.

Arıza sessiz olacak biçimde kurulu. Panelde ödenmiş fatura, bakiyede alacak, sipariş ekranında bekleyen sipariş; hiçbir yerde hata yok. Günler sonra "siparişim nerede" diye yazan müşteriyle ortaya çıkar — üstelik size fazla ödemiş müşteriyle.

Eşitlik yerine kümeye bakın:

// İkisi de faturayı kapatır; fazlayı yalnızca ikincisi taşır.
if (in_array($event['event_type'], ['invoice.paid', 'invoice.paid_over'], true)) {
    $orders->markPaid($event['data']['invoice_id']);
}

Sonra iki rakamı kendi kaydınızda ayrı tutun. İstenen tutar ile gelen tutar iki ayrı sayıdır, fazlalık da aradaki farktır — aylar sonra olay adından geri çıkarılacak bir şey değil. Siparişi yazarken de data içindeki fatura kimliğini kullanın, teslimat kimliğini değil; ikisini karıştırmanın tek ödemeyi iki kez yazdırdığı yer ayrı bir yazının konusu.

Eksik ödeme çoğunlukla borsadan geliyor

İlk akla gelen ağ ücreti, yanlış olan da o. Ethereum'da gas zincirin kendi parasıyla ödenir — "Gas fees have to be paid in Ethereum's native currency, ether (ETH)" — ve gönderen cüzdan bunu kendi ETH bakiyesinden karşılar. Token tutarı bozulmadan yol alır: kendi cüzdanından 200 USDT gönderen müşteri 200 USDT göndermiştir.

Eksik, neredeyse her seferinde borsa hesabından ödeyen müşteriden geliyor. Binance.US kendi çekimleri için bunu açıkça yazıyor: hem borsanın ücreti hem ağ ücreti "are deducted from your withdrawal amount before it reaches your destination wallet". Müşteri fatura tutarını yazdı, borsa o tutardan kendi ücretini kesti, faturanız da tam kesilen kadar eksik kaldı.

İkinci kaynak elle yazılan rakam. Fatura itibari para biriminde fiyatlandıysa kur, ödeyen varlığı ve ağı onayladığı anda — daha hiçbir transfer gönderilmeden — kilitlenir; ekranda duran token tutarı da çoğu zaman uzun bir ondalık kuyrukla gelir. Ödeme sayfasında bunun sonucu yok, çünkü cüzdan bağlantısı tutarı kendisi taşır. Rakamı gerçekten elle yazan yerler var: kamerayla okunan adres QR'ı ve Telegram kartı. Karttaki kopyalama düğmesi tam da bu yüzden duruyor.

Toleransın yüzde olmasıyla sebebin sabit olması burada çarpışıyor. Sabit kesinti küçük faturadan büyük ısırık alır, büyük faturadan fark edilmez; tek bir yüzde ikisini birden karşılamaz. %0,1'de 200 birimlik fatura 0,2 birim yutar; yukarıdaki 1,5 birimlik eksiğin yanında bu, yuvarlama kuyruğundan başka bir şey değil. Toleransı kuyruğa göre ayarlayın; borsa vakası ise olduğu şey olarak kalsın, yani ödeme sayfasında ya da sipariş onayında müşteriye söylenecek bir cümle.

Ne kadar eksik hâlâ ödendi sayılır?

Projenin Eksik ödeme toleransı ne diyorsa o kadar; çizginin altına düşen ödemede kimseye sorulmaz. Tavan %2, kaydırıcı onda bir puanla ilerler, bugün açtığınız proje de ilk adımda — %0,1'de — başlar. Sıfıra çekince eşleşme katılaşır: ödeme ya fatura tutarına ulaşır ya onu geçer. Fatura başına geçersiz kılma yok; oluşturma isteğinde tolerans alanı bulunmaz, dolayısıyla proje ne diyorsa altındaki her fatura onu alır.

Toleransın içinde kalan fatura tamamlanır ve diğer ödenmiş faturalar gibi invoice.paid yayar. Tahsil ettiğiniz şey gelen tutardır, aradaki farkı kimse tamamlamaz.

Sonradan neyi düzeltebileceğinizi tek ayrıntı belirliyor. Fatura, projesinin oluşturma anındaki toleransıyla yargılanır ve o kopya ömrü boyunca faturanın üzerinde donar. Kaydırıcıyı oynatmak bundan sonra keseceğiniz faturaları değiştirir, ödeme sayfasında şu an açık duranları değil.

Eksik ödemenin iki sonu

Aralarında allow_multiple_payments seçer, değer fatura oluşturulurken sabitlenir ve API varsayılanı true.

Birkaç ödemeye açık faturada eksik transfer hiçbir şeyi kapatmaz. Fatura underpaid_waiting durumuna geçer, kalan için açık kalır ve aritmetiği ödeme sayfası üstlenir: QR kod ile cüzdan bağlantıları kalan tutara göre yeniden kurulur, üstelik o rakam sunucuda hesaplanır — çıkarma işlemi tarayıcıya bırakılmaz. Telegram kartındaki tutar kopyalama düğmesi de adını değiştirir ve asıl toplamı değil kalanı kopyalar.

Kapalıyken tek eksik transfer işin sonudur: fatura underpaid kapanır, invoice.underpaid çıkar.

Açık kalanı ise saat bitirir. Ödeme penceresi çizginin altındaki faturada kapanırsa fatura eksik ödenmiş olarak yerleşir — ama algılanmış ve onayı süren transfer bunu doğrudan engeller, çünkü yoldaki paranın altından fatura çekilmez.

Eksik ödenen fatura da para getirir

Getirir; ekstrede tuhaf duran kısım da tam burası.

Her transfer onaylandıkça hesaba geçer, komisyon o transferin kendi tutarından alınır. Kısmi ödeme, fatura hâlâ açıkken bakiyede duran paradır; underpaid biten fatura ise sizi, kapanmamış siparişin karşısında gerçek parayla bırakır.

Olay akışı paradan daha sessiz. invoice.underpaid_waiting fatura o duruma girerken bir kez çıkar. Faturayı yine karşılamayan ikinci eksik transfer bakiyeyi oynatır ama yeni olay üretmez, çünkü durum değişmedi ve webhook durum değişikliğine bağlı. Olay akışı üzerine kurulmuş destek ekranı, iki gelişin yalnızca birini gösterir. Koşan toplamı faturadan okuyun: payment.paid ile payment.remaining orada duruyor.

Geriye kimsenin sizin yerinize veremeyeceği karar kalıyor — yine de gönderin, eksiğiyle gönderin, farkı isteyin ya da parayı geri yollayın. Sonuncusu, fazla ödemedeki gibi, bakiyenizden çıkan sıradan bir transfer.

Faturayı ödemeyen para

Fatura eksik kalabilir. Adrese, o faturayı hiç ödemeyen para da düşebilir; bakiyede ikisi yan yana benzer görünür ve davranışları hiç benzemez.

Her alacağın nedeni kayıtlı, sık görülenler de şunlar: pencere kapandıktan sonra gelen transfer, çoktan kapanmış faturaya gelen transfer, USDT ile fiyatlanmış faturaya USDC gönderen müşteri, üstünde fatura olmayan adrese düşen yatırma. Hepsi olağan işlem komisyonu düşülerek bakiyeye yazılır. Fatura kımıldamaz: ödendi işaretlenmez, eksik ödendi işaretlenmez, hiç değişmez.

Olayı da yok. Farklı bir olay değil — hiç: bu alacağı webhook akışında taşıyacak şey yok. Eksik ödemenin entegrasyonunuzun okuyabileceği durumu ve abone olabileceği olayı var. Bununsa Bakiye sayfasında satırı, e-postası, panel bildirimi ve bağlıysa Telegram mesajı var; sunucunuzun dinleyebileceği hiçbir şeyi yok.

O satır nedeniyle birlikte duruyor: tutar, komisyon, varsa fatura ve bilindiğinde gönderen adresi ile işlem hash'i — bilinmediğinde gönderen yeri "bilinmiyor" kalır. İade etmeye karar verirseniz gereken veri burada; iadenin kendisi yine sizin göndereceğiniz transfer.

Hesap tutmadığında nereye bakacağınızı bu fark söylüyor. Eksik fatura, peşine düşülecek sipariştir. Faturasız alacak ise hiçbir siparişin beklemediği paradır ve orada olduğunu size yalnızca bakiye söyler.

Müşteri denemeden önce siz deneyin

Sandbox'ta, ödeme simülatörüyle — simülatör, gerçek ödemenin yaydığı yaşam döngüsü webhooklarının aynısını yayar. İmzalı tek çağrı, onaylanmış sandbox faturasını istediğiniz sonuca taşır:

POST /v1/sandbox/invoices/inv_7Qk2.../simulate-payment
Content-Type: application/json

{ "stage": "overpaid" }

overpaid beklenenin %10 üzerini öder, underpay beklenenin %40'ını öder ve her rakam faturadan sunucuda türetilir; istemci hiçbir zaman sayı göndermez. Aşamalar üst üste binerek toplanır, yani iki underpay çağrısı aynı faturaya %80 yazar ve fatura hâlâ eksiktir.

Üç çağrı, sizin tarafınızda üç ayrı iddiayı sınıyor:

• underpay, allow_multiple_payments kapalı açılmış faturada — eksik kapanan faturayı kendi kaydınızın nasıl yazdığını. Para bakiyede görünmeli, sipariş açıkta kalmalı.
• underpay, birkaç ödemeye açık faturada — destek ekibinizin baktığı ekranın asıl toplamı değil kalanı gösterdiğini.
• overpaid, sipariş kapatma yolunuzun izlediği faturada — o yolun invoice.paid_over olayını da kabul ettiğini. Sipariş çıkmazsa hata ikinci başlıkta yazıyor.

Bu yolla prova edilemeyen tek dal tolerans: kıl payı eksik kalan ödeme için aşama yok, o ayar test atarak değil projede okunarak doğrulanır. Geri kalan her şey imzalı tek istek uzağınızda.