OxaPay Webhook'ları Nasıl Kurulur? Pratik Rehber

Müşterinin kripto para ödemesini tamamlaması, iş akışının yalnızca başlangıcıdır. Web sitenizin veya uygulamanızın hâlâ sonucu doğrulaması, doğru siparişi güncellemesi, müşteriyi bilgilendirmesi ve siparişin karşılanmasına başlanıp başlanamayacağına karar vermesi gerekir. OxaPay webhook'ları ödeme durumu güncellemelerini doğrudan sunucunuza göndererek bunu mümkün kılar.

Güvenilir bir webhook entegrasyonu, bildirim almaktan fazlasını yapar. Geri çağrının gerçekliğini doğrular, doğru ödemeyle eşleştirir, tekrarlanan iletimleri güvenle yönetir ve bilgiler geciktiğinde veya belirsiz olduğunda durum sorgulaması yapar. Bu rehber, işletme sahipleri, ürün ekipleri ve geliştiriciler için sürecin tamamını pratik biçimde açıklar.

OxaPay Webhook'u Ne İşe Yarar?

Webhook, bir olayla tetiklenen sunucudan sunucuya mesajdır. Sisteminiz bir ödemenin değişip değişmediğini sürekli sorgulamak yerine, yeni ödeme bilgileri kullanılabilir olduğunda OxaPay'in belirttiğiniz HTTPS URL'sine JSON biçiminde geri çağrı göndermesini sağlar.

Uygulamanız doğrulanmış güncellemeyi kullanarak sipariş durumunu değiştirebilir, hizmet etkinleştirebilir, onay gönderebilir veya  mutabakatiçin kayıt oluşturabilir. Bu özellikle yararlıdır; çünkü kripto para ödemesi nihai ticari sonuca ulaşmadan önce birden fazla durumdan geçebilir.

Tarayıcıdaki dönüş sayfası ödeme kanıtı sayılmamalıdır. Müşteri sayfayı kapatabilir, bağlantısını kaybedebilir veya ödeme gerekli duruma ulaşmadan dönüş URL'sini ziyaret edebilir. Siparişin yerine getirilmesi kararı, sunucu tarafında doğrulanmış ödeme bilgilerine dayanmalıdır.

İşletmeniz Ne Zaman Ödeme Webhook'una İhtiyaç Duyar?

Özel bir webhook, ödeme sonucunun otomatik olarak başka bir işlemi başlatması gerektiğinde en değerlidir. Yaygın örnekler şunlardır:

• e-ticaret siparişini beklemede durumundan gönderime hazırlığa taşımak;
• bir SaaS hesabını etkinleştirmek veya aboneliği uzatmak;
• e-posta, SMS ya da uygulama içi mesajla ödeme onayı göndermek;
• stok, CRM, muhasebe veya kurum içi raporlama sistemlerini güncellemek;
• ödeme  eksik yapıldığında veya süresi dolduğundaya da başka nedenle incelenmesi gerektiğinde operasyon ekibini uyarmak.

Desteklenen bir ödeme eklentisikullanıyorsanız bu mantığın büyük bölümü entegrasyon tarafından zaten yönetiliyor olabilir. Yalnızca ara sıra  Payment Links and review them manually, you may not need a custom endpoint. Doğrudan API entegrasyonları and custom platforms usually benefit the most.

OxaPay Webhook Akışı Nasıl Çalışır?

1. Your system creates or identifies a payment and stores OxaPay’s track_id with your own order or customer reference.
2. Müşteri ödemeyi gönderir; OxaPay işlemi işlerken ödeme durumu değişir.
3. OxaPay, yapılandırılmış geri çağrı URL'nize imzalı JSON mesajı gönderir.
4. Sunucunuz mesaja güvenmeden önce imzayı doğrular.
5. Sunucunuz geri çağrıyı doğru kayıtla eşleştirir ve önemli ödeme bilgilerini doğrular.
6. Uygulamanız olayı kaydeder, onaylanan her iş işlemini yalnızca bir kez gerçekleştirir ve başarılı HTTP yanıtı döndürür.

Bu ayrım önemlidir. Webhook ödeme güncellemesini iletir; ancak güncellemenin sipariş, hesap, sevkiyat veya defter kaydı için ne anlama geldiğine karar vermek uygulamanızın sorumluluğundadır.

Başlamadan Önce

Geri çağrıyı bağlamadan önce aşağıdakileri hazırlayın:

• HTTP POST isteklerini kabul eden, internete açık bir HTTPS uç noktası;
• güvenle saklanan ve tarayıcı kodunda asla açığa çıkarılmayan ilgili OxaPay üye işyeri kimlik bilgilerine sunucu tarafında erişim;
• OxaPay kimliği olan  track_id with your own order, invoice, or user ID;
• hangi ödeme durumlarının sipariş karşılama, erişim verme, iade, bildirim veya manuel inceleme başlatabileceğine ilişkin açık kurallar;
• iletim hatalarını, doğrulama hatalarını ve beklenmedik durum değişikliklerini ortaya çıkaran günlükleme ve izleme.

Daha kapsamlı bir entegrasyon planlıyorsanız  kripto ödeme entegrasyonu kontrol listesini to review keys, payment methods, callbacks, testing, and go-live controls together.

OxaPay Webhook'ları Nasıl Kurulur?

Ödeme Durumu Kurallarınızı Belirleyin

İşleyiciyi yazmadan önce her  ödeme durumu before writing the handler. A notification that a payment has started is not the same as a completed payment. Underpaid, expired, refunded, or other exception states may require a different action or a manual review.

Yalnızca belgelenmiş ve beklenen durum geçişlerine izin verin. Örneğin daha önce yerine getirilmiş bir sipariş, aynı geri çağrı iki kez iletildi diye tekrar yerine getirilmemelidir.

Güvenli Bir Geri Çağrı Uç Noktası Oluşturun

Arka ucunuzda  https://example.com/webhooks/oxapaygibi özel bir HTTPS yolu oluşturun. POST isteklerini kabul etmeli, imza doğrulaması için ham istek gövdesine erişimi korumalı, desteklenmeyen yöntemleri veya bozuk istekleri reddetmelidir.

İşleyicinin kapsamını dar tutun. İlk görevi geri çağrıyı doğrulamak ve kalıcı biçimde kaydetmektir. E-posta göndermek, birden fazla dış sistemi güncellemek veya rapor üretmek gibi yavaş işler, olay kabul edildikten sonra arka plan kuyruğuna aktarılabilir.

Geri Çağrı URL'sini OxaPay'e Bildirin

Geri çağrı URL'sini ilgili OxaPay ödeme akışına ekleyin. Ürüne veya entegrasyon yöntemine göre URL, ödeme isteğinde ya da geçerli üye işyeri yapılandırmasında sağlanabilir. Hizmetin tam alanını ve davranışını öğrenmek için  OxaPay Webhook belgeleri for the exact field and behavior of the service you are implementing.

Her ortamda aynı URL'yi tutarlı biçimde kullanın. Test olaylarının canlı siparişleri değiştirememesi için test ve üretim uç noktalarını ayrı tutun.

Geri Çağrıya Güvenmeden Önce İmzayı Doğrulayın

OxaPay belgelerine göre HMAC-SHA512 imzası, üye işyeri API anahtarı ortak gizli anahtar olarak kullanılarak ham POST verilerinden üretilir. Sunucunuz değiştirilmemiş ham gövdeden beklenen imzayı hesaplamalı ve geri çağrıyla gelen imzayla karşılaştırmalıdır.

Doğrulama başarısızsa isteği reddedin. Çatınız destekliyorsa sabit zamanlı karşılaştırma kullanın ve üye işyeri API anahtarını veya diğer gizli bilgileri asla günlüğe yazmayın. HMAC hesaplamadan önce JSON'u ayrıştırıp yeniden serileştirmek boşlukları veya alan sırasını değiştirebilir ve geçerli imza kontrolünü başarısız kılabilir.  Geri çağrı doğrulama kaynağı explains the broader security model.

Ödemeyi Eşleştirin ve Doğrulayın

Geçerli imza mesajın kaynağını doğrular; ancak uygulamanız iş verilerini de doğrulamalıdır.  track_id to a known payment record, confirm the relevant order or customer reference, compare the expected amount and currency where applicable, and check that the new state is allowed from the current state.

Bilinmeyen bir ödemenin, beklenmedik tutarın veya geçersiz durum geçişinin sipariş karşılamayı otomatik başlatmasına izin vermeyin. Olayı inceleme için kaydedin ve güncel ödeme bilgilerini API aracılığıyla doğrulayın.

Her Olayı İdempotent Biçimde İşleyin

Webhook iletimi tekrarlanabilir. İşleyiciniz aynı ödeme güncellemesini birden fazla aldığında aynı nihai sonucu üretmelidir. Sabit bir olay veya ödeme durumu anahtarı saklayın ve e-posta göndermeden, erişim vermeden, stok değiştirmeden ya da muhasebe kaydı oluşturmadan önce kontrol edin.

İdempotentlik, yinelenen iletimi ikinci sevkiyata, tekrarlanan abonelik uzatmasına veya çift defter kaydına değil, zararsız yeniden denemeye dönüştürür.

Olayı Kaydedin ve Hızla Yanıtlayın

İstek doğrulamayı geçtikten sonra HTTP  200 with the expected ok response. If downstream work may take time, place it in a queue and respond after durable receipt rather than making the sender wait for the entire business workflow.

Sunucunuz olayı güvenli biçimde kaydedemiyorsa hata yanıtı döndürün ve sorunu araştırın. Bir geri çağrıyı onaylayıp daha sonra sessizce atmayın.

Ödemenin Tüm Yaşam Döngüsünü Test Edin

Tek bir başarılı geri çağrıyı test etmekle yetinmeyin. Geciken ödeme, eksik ödeme, süre dolması, yinelenen iletim, geçersiz imzalar ve bilinmeyen  track_id values, temporary database failure, and recovery after downtime.

Hem teknik hem ticari sonucu doğrulayın. Uç nokta  200 OK while the wrong order is updated or the customer receives two confirmations. A complete test follows the event from OxaPay through your database, queue, customer message, fulfillment logic, and audit trail.

Webhook'ları Durum Sorgulamalarıyla Birlikte Kullanın

Webhook'lar ve API durum sorguları aynı sorunun farklı bölümlerini çözer. Webhook hızlı sinyal verir. Durum isteği ise geri çağrı geciktiğinde, kaçırıldığında, sıra dışı işlendiğinde veya yerel kesinti sonrasında belirsiz kaldığında güvenilir bir kurtarma yolu sağlar.

For important payment flows, schedule reconciliation for records that remain pending too long or have not received an expected update. OxaPay’s Payment Information API can be used to retrieve the current payment details by the documented identifier.

Pratik Webhook Kullanım Senaryoları

E-ticaret Siparişleri

Ödeme devam ederken siparişi beklemede tutun. Doğrulanmış tamamlanma durumundan sonra işletme kurallarınıza göre stoğu ayırın veya serbest bırakın, siparişi yalnızca bir kez karşılama aşamasına geçirin ve müşteriye onay gönderin.

SaaS ve Dijital Erişim

Hesabı ancak doğrulanmış ödeme sonucundan sonra etkinleştirin veya erişimi uzatın. Aynı faydanın tekrarlanan geri çağrıyla ikinci kez verilmemesi için ödeme dönemini ya da yetki değişikliğini kaydedin.

Finans ve mutabakat

Ödeme olaylarını denetim izine ekleyin ve kurum içi faturaya bağlayın. İstisnai durumlar inceleme kuyruğuna alınabilir; zamanlanmış durum sorgulamaları ise sonuçlanmamış ödemeleri mutabık hâle getirir.

Müşteri İletişimi

Mesajları gelen her geri çağrıdan doğrudan göndermek yerine idempotent iş akışınızın sonucuna göre gönderin. Böylece ödeme farklı durumlardan geçerken yinelenen e-postalar veya çelişkili mesajlar önlenir.

Yaygın Webhook Hataları

• Dönüş sayfasına güvenmek: use verified server-side payment information instead of a browser redirect.
• Yeniden biçimlendirilmiş JSON'u doğrulamak: calculate the HMAC from the original raw request body.
• Üye işyeri anahtarını açığa çıkarmak: keep signing credentials in protected server-side storage.
• Her geri çağrının benzersiz olduğunu varsaymak: make every business action idempotent.
• Yanıt vermeden önce çok fazla iş yapmak: durably record the event, queue slow work, and respond promptly.
• Her durum geçişini kabul etmek: enforce a controlled payment state model.
• Yalnızca iletime güvenmek: use payment information requests for recovery and reconciliation.
• Hassas verileri günlüğe yazmak: retain useful identifiers and validation results without storing secrets unnecessarily.

OxaPay Webhook Sorunlarını Giderme

OxaPay Webhook Canlıya Geçiş Kontrol Listesi

• Üretim geri çağrısı HTTPS kullanır ve genel internetten erişilebilir durumdadır.
• Ham istek gövdesi, HMAC-SHA512 doğrulaması tamamlanana kadar korunur.
• Üye işyeri API anahtarı güvenli saklanır; istemci kodunda veya günlüklerde asla bulunmaz.
• Her geri çağrı bilinen bir ödemeyle eşleştirilir ve beklenen iş verilerine göre doğrulanır.
• İzin verilen ödeme durumu geçişleri belgelenir ve uygulanır.
• Yinelenen geri çağrılar sipariş karşılama, erişim, bildirim veya muhasebe kayıtlarını tekrar edemez.
• Olaylar ve doğrulama sonuçları gereksiz hassas veriler olmadan günlüğe kaydedilir.
• Geciken veya belirsiz ödemeler Payment Information API üzerinden mutabık hâle getirilebilir.
• İzleme, imza hataları, işleme hataları ve büyüyen kuyruklar hakkında ekibi uyarır.
• Gerçek müşteri ödemeleri bu sürece bağlı hâle gelmeden önce tüm iş akışı test edilmiştir.

Sonraki Adım Nedir?

Önce her ödeme durumu için izin verilen iş işlemini tanımlayın. Ardından sonraki işleri tetiklemeden önce geri çağrıları doğrulayan, kaydeden ve yinelenenleri ayıklayan güvenli bir uç nokta oluşturun. Son olarak geçici iletim veya sistem arızasının siparişi süresiz çözümsüz bırakmaması için durum kontrolü ve mutabakat yolu ekleyin.

Ödeme durumları, iletim ve kurtarma mimarisi hakkında daha fazla bilgi için  Blokzincir Ödeme Sistemlerinde Gerçek Zamanlı İzlemeyazısını okuyun. Geliştiriciler uygulamada  güncel OxaPay webhook belgelerini as the implementation source of truth.