MercanPay Blog

Fatura Durumu Sorgulama: API ile Ödeme Kontrolü Nasıl Yapılır?

Fatura durumunu API ile sorgulama rehberi: fatura kimliği ve order_id ile kontrol, sorgulama sıklığı ve webhook ile birlikte güvenli kullanım.

Yayınlanma: 19 Kasım 20263 dk okumaRead in English
Fatura Durumu Sorgulama: API ile Ödeme Kontrolü Nasıl Yapılır?

Fatura durumunu API ile sorgulamak, webhook'larınızı bir güvenlik ağıyla tamamlamanın en basit yoludur. MercanPay'de GET /v1/invoices/:id ve GET /v1/invoices/by-order/:order_id uç noktalarıyla bir faturanın güncel durumunu istediğiniz an öğrenebilirsiniz. Bu yazıda fatura durumunu ne zaman, nasıl ve hangi sıklıkla sorgulamanız gerektiğini anlatıyoruz.

Neden fatura durumu sorgulamalısınız?

Ödeme bildirimlerinin ana kanalı webhook'lardır: ödeme geldiğinde MercanPay sunucunuza invoice.paid gibi olaylar gönderir ve başarısız teslimatları artan aralıklarla yeniden dener. Yine de sorgulama (polling) şu durumlarda işinize yarar:

  • Sunucunuz bakım nedeniyle kısa süre kapalıydı ve bir olayı kaçırdığınızdan şüphelendiniz.
  • Müşteri ödeme sayfasından sitenize döndü ve siparişin durumunu hemen göstermeniz gerekiyor.
  • Destek ekibiniz tek bir siparişin ödeme durumunu elle doğrulamak istiyor.
  • Gün sonu mutabakatında "açık kalmış" faturaları tarayıp kontrol etmek istiyorsunuz.

Webhook kurulumu için Webhook Olay Türleri ve Webhook Yeniden Deneme ve İdempotent İşleme yazılarına bakabilirsiniz. Sorgulama, bunların yerine değil, yanında çalışır.

İki sorgulama yolu

1. Fatura kimliğiyle: GET /v1/invoices/:id

Fatura oluşturduğunuzda MercanPay size bir fatura kimliği verir. Bu kimliği siparişinizin yanında saklarsanız, doğrudan bu uç noktayla durumu öğrenebilirsiniz.

2. Sipariş numarasıyla: GET /v1/invoices/by-order/:order_id

Faturayı oluştururken kendi sipariş numaranızı order_id olarak gönderdiyseniz, fatura kimliğini saklamanıza gerek kalmadan siparişinizden faturaya ulaşabilirsiniz. Sipariş numarası kullanımının ayrıntıları order_id ile Fatura Sipariş Eşleştirme yazısında anlatılıyor.

İstek başlıkları, kimlik doğrulama biçimi ve yanıt alanlarının tam listesi için güncel dokümantasyona bakın; bu yazıda yalnızca akışı anlatıyoruz.

Fatura durumları ve ne anlama gelir?

Bir fatura yaşam döngüsü boyunca şu olaylarla ilişkili durumlardan geçer:

Olay Anlamı
invoice.paid Ödeme tamamlandı ve 20 blok onayından sonra hesabınıza işlendi
invoice.partial Eksik ödeme geldi; fatura uzatılır, müşteri kalanı gönderebilir
invoice.overpaid Fazla ödeme geldi
invoice.expired Süre doldu (faturalar en fazla 24 saat açık kalır)
invoice.cancelled Fatura iptal edildi

Geç gelen ödemeler de hesabınıza yansıtıldığı için, süresi dolmuş bir faturanın durumunu sorgularken bile sonradan ödeme gelmiş olabileceğini unutmayın. Bu konunun ayrıntıları için Eksik, Fazla ve Geç Kripto Ödemeler yazısına göz atın.

Sorgulama akışı nasıl tasarlanır?

Kod yazmadan önce mantığı kurmak daha sağlıklıdır:

  1. Siparişi oluştururken faturayı order_id ile birlikte oluşturun ve fatura kimliğini kaydedin.
  2. Müşteri sitenize döndüğünde (başarı sayfası) sipariş durumunu önce kendi veritabanınızdan okuyun; webhook büyük olasılıkla çoktan işlenmiştir.
  3. Kayıt henüz "ödendi" değilse, fatura durumunu API'den sorgulayın ve sonucu ekranda gösterin.
  4. Ödeme algılanıp onay bekliyorsa müşteriye "ödemeniz onaylanıyor" mesajı gösterin. Onay genellikle yaklaşık bir dakika sürer.
  5. Durum kesinleşince siparişi tamamlayın ve bunu yalnızca bir kez yapın.

Sıklık ve sınırlar

  • Saniyede birkaç istek yerine 10-30 saniyelik aralıklar kullanın. Onay süresi dakika mertebesindedir; daha sık sorgu fayda sağlamaz.
  • Faturanın açık kalabileceği en fazla süre 24 saattir; bu süreden uzun sorgulamaya gerek yoktur.
  • Durum "ödendi", "süresi doldu" veya "iptal" olunca sorgulamayı durdurun.
  • Sorgu sonucuyla webhook aynı siparişi ikinci kez tamamlamamalı: işlemi idempotent tasarlayın.

Yaygın hatalar

  1. Yalnızca polling'e güvenmek. Sorgu aralarında gelişmeleri geç görürsünüz; webhook ana kanalınız olmalıdır.
  2. Yalnızca tarayıcıdaki yönlendirmeye güvenmek. Müşterinin başarı sayfasına dönmesi ödemenin gerçekleştiğini kanıtlamaz; durumu sunucu tarafında doğrulayın.
  3. Siparişi iki kez tamamlamak. Hem webhook hem sorgu "ödendi" dediğinde teslimatı tekrarlamayın.
  4. API anahtarını tarayıcıya koymak. Sorguları yalnızca sunucunuzdan yapın.
  5. Fatura kimliğini kaydetmemek. order_id kullanmıyorsanız kimliği sipariş kaydınızda tutun.

Sık sorulan sorular

Webhook varken polling gerekli mi?

Zorunlu değildir ama güvenlik ağı olarak önerilir. Webhook'lar yeniden denenir; yine de kaçırılan bir olayı sorgulayarak yakalayabilirsiniz.

Faturayı sipariş numarasıyla bulabilir miyim?

Evet. Faturayı order_id ile oluşturduysanız GET /v1/invoices/by-order/:order_id ile sorgulayabilirsiniz.

Ne kadar sıklıkla sorgulamalıyım?

10-30 saniyelik aralıklar yeterlidir. Ödeme onayı genellikle yaklaşık bir dakika sürer.

Süresi dolmuş faturaya ödeme gelirse?

Geç ödemeler yine de hesabınıza yansıtılır. USD fiyatlı TRX faturalarında güncel kurla yeniden fiyatlanır.

MercanPay ile başlayın

Webhook ve sorgulamayı birlikte kullanarak siparişlerinizi güvenle otomatikleştirin. Satıcı başvurusu yapın ve tüm uç noktaları dokümantasyonda inceleyin.

#API#fatura sorgulama#order_id#webhook#polling#entegrasyon

İlgili yazılar

Kripto ödemeleri dakikalar içinde almaya başlayın

USDT ve TRX (TRC20) ile ödeme alın. %0,4'ten başlayan komisyon, hazır ödeme sayfası, API ve webhook.