Kripto ödemeleri müşteri siparişleriyle eşleştirme

Bir kripto ödemeyi doğru müşteri siparişiyle eşleştirmek için önce merchant sisteminde kararlı bir order ID oluşturun. Bu ID’yi ayrı bir payment invoice’a bağlayın ve sağlayıcının invoice ID’sini siparişte saklayın. İmzalı webhook veya authenticated API paid sonucu verdiğinde merchant reference ile siparişi bulun, invoice durumunu doğrulayın, token, ağ, tutar ve tx hash’i kaydedin ve fulfilment’ı idempotent çalıştırın. Güvenilir ilişki merchant order ID → payment invoice ID → confirmed blockchain transaction şeklindedir.

Kayıt	Kanıtladığı şey	Tek başına kanıtlayamadığı şey
Merchant order	Müşteri yükümlülüğü ve fulfilment anlamı	Fonların on-chain geldiği
Payment invoice	Beklenen token, ağ, tutar ve süre	Merchant’ın ürünü teslim ettiği
Blockchain transaction	Kamuya açık token transferi	Hangi ticari sipariş için gönderildiği
İmzalı payment event	Hizmetin invoice ile işlemi eşleştirdiği	Downstream işlemin yalnızca bir kez uygulandığı

Blockchain işlemi sipariş numaranızı bilmez

Blockchain varlık hareketini kaydeder. ERC-20 Transfer olayı göndereni, alıcıyı ve değeri içerir; ERC-20 standardı ecommerce order ID, müşteri hesabı, SKU veya teslim kuralı taşımaz. 100 USDC’nin cüzdana gelmesi bir transferi kanıtlar, fakat bunun ORDER-4821, eski bir invoice veya ilgisiz işlem olduğunu açıklamaz.

Bağlantıyı checkout müşteriye gönderilmeden önce kurun. Fon geldikten sonra address, amount veya time üzerinden tahmin yapmak her benzer ödemeyi destek ekibinin problemi hâline getirir.

Address, amount veya screenshot ile join yapmayın

Ortak alıcı adresi siparişe özgü değildir. İki müşteri aynı tutarı aynı adrese gönderebilir; biri eski talimatı yeniden kullanabilir; aynı 0x adres biçimi farklı EVM ağlarında görünebilir. Amount da benzersiz değildir: eşit fiyatlar, underpayment, overpayment ve rounding mümkündür. Alışılmadık decimal tutarlar çakışmayı azaltabilir fakat açık order-to-invoice ilişkisinin yerini tutmaz.

Doğrulanan tutar faturadan farklıysa eksik ve fazla ödeme iş akışını kullanın ve siparişi normal otomatik fulfilment dışında tutun.

Timestamp ve sender address yalnızca yardımcı kanıttır. Borsa çekimleri gecikebilir veya ortak altyapı adresinden gelebilir. Screenshot ödeme kanıtı değildir; gerçek bir tx hash bile yanlış token, recipient, network ya da daha önce kullanılan transferi gösterebilir. Manuel doğrulama rehberi on-chain alanların nasıl kontrol edileceğini açıklar.

Üç kaydı açık foreign key’lerle bağlayın

Alan	Nerede saklanır	Amaç
Local order ID	Merchant database ve payment context	Sipariş lookup ve fulfilment anahtarı
Payment invoice ID	Merchant order ve provider	Doğrudan erişim ve destek referansı
Beklenen iş tutarı	Merchant order	Ticari borç
Payable token amount	Payment invoice	Checkout’taki kesin tutar
Token ve network	Invoice ve final payment record	Farklı rotaları ayırmak
Status ve history	Payment record	İzin verilen iş adımını belirlemek
Transaction hash	Final payment record	Public blockchain kanıtını bulmak
Paid/expiry timestamps	Payment record	Geç ve süresi dolmuş ödemeleri açıklamak
Event/delivery key	Webhook inbox	Tekrarlanan side effect’i önlemek

Değiştirilemeyen database ID veya UUID kullanın. Personelin düzenleyebildiği ekran numarası güvenilir foreign key değildir. Metadata içine secret, private key veya gereksiz müşteri verisi koymayın. Invoice oluşturulur oluşturulmaz provider ID’yi order’a yazın; böylece destek iki yönde de kayıtları bulabilir.

Invoice’ı tekrar güvenli şekilde oluşturun

Web sitesi önce local order’ı payment_pending durumunda oluşturur, sonra bu order ve payment attempt’ten sabit bir idempotency key üretir. Payment invoice’a order ID eklenir, dönen invoice ID ve checkout URL kaydedilir ve ancak bundan sonra müşteri yönlendirilir.

Timeout belirsizdir: provider invoice’ı oluşturmuş fakat cevap merchant’a ulaşmamış olabilir. Yeni key ile tekrar etmek ikinci aktif checkout oluşturur. GramPayBot’ta merchant reference payload alanına gönderilir. Aynı Idempotency-Key ve aynı parametrelerle tekrar orijinal invoice’ı döndürür; farklı parametrelerle yeniden kullanım conflict üretir. Ayrıntılar API quickstart ve API reference içindedir.

Bir sipariş zaman içinde birden fazla attempt içerebilir: order → attempt 1 expired → attempt 2 paid. Eski kaydı silmeyin. Yalnızca bir attempt order’ı otomatik kapatabilmeli; diğerleri geç ödeme incelemesi için kalmalıdır.

Son order geçişini sunucu yapsın

Browser return page ödeme otoritesi değildir. Müşteri sayfayı erken kapatabilir veya eski success URL’yi tekrar açabilir. Fulfilment authenticated API lookup veya imzalı server-to-server webhook üzerinden başlamalıdır.

Güvenli handler sırası:

1. Exact raw body’yi okuyun ve HMAC imzasını constant time ile doğrulayın.
2. Delivery ve body’yi yavaş iş mantığından önce saklayın.
3. Stable event veya delivery key ile deduplicate edin.
4. Geçerli isteğe hızla 2xx verin.
5. Async worker içinde order ve payment attempt’i saklanan ID’lerle bulun.
6. Yalnızca izin verilen state transition’ı uygulayın.
7. Payment record ile fulfilment marker’ı mümkünse atomik commit edin.

GramPayBot gerçek event’leri yaklaşık dört gün boyunca 17 defaya kadar tekrarlar. Duplicate delivery bir hata değil güvenilirlik mekanizmasıdır. Stripe’ın resmî webhook uygulamaları da işlenen event ID’lerinin saklanmasını önerir.

Delivery deduplication tek başına yetmez. Webhook ve polling worker aynı paid invoice’ı görebilir. Business action’ı unique constraint veya conditional update ile koruyun: order yalnızca payment_pending durumundan geçebilsin ve her order için tek fulfilment job oluşsun. Hedef exactly-once delivery değil, at-least-once delivery ile exactly-once business effect’tir.

Status’ları izin verilen eylemlere bağlayın

Payment state	Merchant anlamı	Otomatik eylem
active	Geçerli invoice, kabul edilmiş ödeme yok	Order pending kalır
paid	Invoice onay kuralını karşıladı	İdempotent fulfilment’a izin verilir
expired	Ödeme penceresi eşleşme olmadan bitti	Normal fulfilment durur, late payment incelenir
cancelled	İstek bilinçli kapatıldı	Güncel attempt olarak kabul edilmez

Payment status ile order status aynı olmak zorunda değildir. paid invoice, stok veya compliance kontrolü gereken üründe ready_for_review oluşturabilir. expired invoice ticari order’ı tamamen iptal etmeyebilir; yeni attempt açılabilir. Status history’yi ve manuel override yapan kişiyi saklayın.

Mismatch vakalarını görünür tutun

Wrong token contract, wrong network, underpayment, overpayment, late payment, duplicate tx hash ve local order bulunamaması normal paid yoluna sokulmamalıdır. Gerçek transaction evidence’i silmeden exception state’e alın. Yetkili çalışan ödemeyi kabul etme, fark isteme veya refund kararı verir. Direct-to-wallet modelinde refund’ı merchant cüzdanı imzalar; monitoring service işlemi geri çeviremez.

Operational matching ile accounting reconciliation aynı değildir. Muhasebe fiat value, fee, conversion, refund ve yasal belge de isteyebilir. Günlük kontrol, paid payment attempts ile paid orders’ı karşılaştırmalı; yalnız bir tarafta kalan kayıtları ve duplicate hash’leri işaretlemelidir. Ethereum token transferleri smart-contract event logları ile aranabilir, fakat bu loglar merchant’ın ticari anlamını içermez.

GramPayBot örneği

SaaS önce ORDER-4821 oluşturur. Backend createInvoice çağrısında payload: "ORDER-4821" ve Idempotency-Key: ORDER-4821:crypto:1 gönderir, dönen public_id ile checkout URL’yi kaydeder. Müşteri Base üzerinde gösterilen USDC tutarını öder. GramPayBot eşleşen işlemi onaylayıp order reference, token, network ve tx hash içeren imzalı invoice_paid event’i gönderir. Endpoint imzayı doğrular, delivery’yi saklar ve 2xx verir. Worker pending order’ı kilitler ve yalnızca bir aktivasyon işi oluşturur. Retry alınır fakat ikinci aktivasyon oluşmaz.

Otomatik ödeme doğrulama rehberi daha geniş detection sürecini, web sitesi kullanım senaryosu ise bu modelin satış akışındaki yerini gösterir.

Launch öncesinde aynı idempotency key ile invoice creation’ı tekrarlayın, aynı webhook’u iki kez gönderin, bir invoice’ı expire edin ve yanlış tutarı fulfilment vermeden test edin. Her paid order tek bir invoice ve kabul edilmiş transaction’a kadar izlenebiliyor, her retry ise duplicate side effect yerine güvenli no-op veya görünür review item üretiyorsa entegrasyon hazırdır.