REST API ile Kripto Ödeme: Üretime Hazır Rehber

Kripto ödeme REST API'si, satıcı sunucusunun fatura oluşturmasını, alıcıyı ödeme deneyimine yönlendirmesini ve blokzincir onayından sonra siparişi teslim etmesini sağlar. Üretim entegrasyonu örnek payload'a bağlı değildir. Dört kalıcı sözleşmeye dayanır: kimliği doğrulanmış istekler, sabit harici sipariş tanımlayıcısı, doğrulanmış webhooklar ve teslimat tekrarlandığında doğru kalan yerel sipariş geçişi.

Paymos aynı Merchant API yüzeyini Sandbox ve Production'da ayrı kimliklerle sunar. API; fatura ve çekim oluşturabilir, getirebilir ve iptal edebilir, bakiyeleri okuyabilir, Sandbox'ta desteklenen sonuçları simüle edebilir ve genel Low-Code SDK faturaları oluşturabilir.

Merchant API neyi yönetebilir?

Ödeme tarafı fatura oluşturma, getirme ve iptali kapsar. Satıcı sunucusunun kendi sipariş tanımlayıcısını Paymos faturasına bağlamasını ve sonra müşteriye dönük entegrasyonu seçmesini sağlar: Hazır Ödeme Sayfası, gömülü iframe, Low-Code SDK veya satıcının sipariş akışı etrafında kurulmuş başka arayüz.

Ödeme Çıkışı (Payout) tarafı çekim oluşturur, getirir ve iptal eder; bakiye işlemleri mevcut varlık bakiyelerini açar. Bu yetenekler Ödeme işlemlerinden ayrı kimlikler kullanır. Sandbox desteklenen ödeme ve çekim sonuçlarını da simüle edebilir. Her yeteneği, ödeme ekranı, finans ve tarayıcı kodunda tek sır paylaşmak yerine servisin ihtiyaç duyduğu en küçük kimlik kapsamının arkasında tutun.

API istekleri nasıl doğrulanmalı?

Paymos Merchant API kimlik doğrulaması HMAC-SHA256 kullanır. Bearer token doğrulaması değildir. HMAC, isteği paylaşılan sırra sırrı kimlik bilgisi olarak göndermeden bağlar ama entegrasyon yine sırrı dururken ve dağıtım sırasında korumalıdır.

İstekleri yalnızca güvenilir sunucuda imzalayın. Merchant API sırrını JavaScript'te, mobil pakette, genel depoda veya analitik loglarında açmayın. Ödeme ve Ödeme Çıkışı kimlikleri ayrıdır; yalnızca fatura oluşturan ödeme ekranı servisi Ödeme Çıkışı kimliği tutmamalıdır. Kimlikleri kontrollü dağıtım süreciyle döndürün ve önceki dağıtımın emekli sırrı kullanmaya devam etmesini engelleyin.

Ortamlar ve kimlikler nasıl ayrılmalı?

Sandbox ve Production aynı API yüzeyiyle ayrı kimlikler kullanır. Bu, Sandbox'ı gerçek blokzincir varlığı göndermeden entegrasyon davranışını doğrulamak için faydalı kılar ama ortamları birbirinin yerine geçebilir yapmaz.

Ortama özgü sırları farklı adlarla saklayın, temel yapılandırmalarını ayrı tutun ve ortamı operasyonel loglara dahil edin. Sandbox servisi asla Production kimliği almamalıdır. Entegrasyon gerçek ödemelere geçtiğinde iş mantığını yeniden yazmak yerine ortam yapılandırmasını değiştirin. Aynı kural webhook sırları için de geçerlidir: alan taraf, siparişi değiştirmeden önce olayı hangi ortamın ürettiğini bilmelidir.

Tekrarlar arasında faturalar güvenli nasıl oluşturulur?

external_order_id değerini satıcının sipariş sisteminde üretin ve o siparişin ömrü boyunca sabit tutun. Paymos bu arayan tarafından verilen değeri fatura oluşturmada kullanır. Aynı harici sipariş tanımlayıcısının yeniden kullanılması yenisini açmak yerine mevcut faturayı döndürür; bu işlem için ayrı Idempotency-Key başlığı yoktur.

Siparişle Paymos faturası arasındaki ilişkiyi kalıcı kaydedin. Bağlantı arayan yanıtı almadan düşerse aynı external_order_id ile tekrar deneyin. Sırf HTTP denemesi değişti diye asla yeni değer üretmeyin. Tanımlayıcı ağ isteğini değil iş siparişini temsil eder.

Fatura oluşturmadan sonra hangi ödeme yüzeyi gelir?

Hazır Ödeme Sayfası mobil uyumlu sayfa, QR ödeme ve desteklenen cüzdan derin linkleri sağlar. Yönlendirme olarak veya iframe içinde gömülü kullanılabilir. Low-Code SDK; sabit tutarları, JavaScript tutar geri çağrısını, DOM tutar kaynağını ve özel buton akışını destekler, iframe ve yönlendirme modları vardır.

Ödeme linkleri alıcıyla doğrudan paylaşılan faturalara uyar. Resmi CMS eklentileri WooCommerce, WHMCS, OpenCart, PrestaShop, Magento 2, Shopware 6, CS-Cart ve Easy Digital Downloads'u kapsar. Host-to-Host ürünü, satıcı sunucusu desteklenen Paymos ödeme deneyimini kullanmaya devam ederken sipariş oluşturma, durum geçişleri ve teslimata sahip olmalıysa doğru yüzeydir.

Webhook imzaları nasıl doğrulanmalı?

Her Paymos webhooku X-Webhook-Signature başlığını t={timestamp},v1={hmac_hex} biçimiyle kullanır. HMAC-SHA256 imzasını yapılandırılmış webhook sırrıyla yeniden hesaplayın ve zamanlama-güvenli eşitlik kontrolüyle karşılaştırın. Kimlik doğrulama, olay faturayı, siparişi, stok düzeyini veya yetkiyi değiştirmeden önce olmalıdır.

Webhook sırrı rotasyonu, güncel ve önceki sırdan imzaların kabul edilebildiği bir tolerans dönemi içerir. Alan tarafı o geçiş için yapılandırın, sonra tolerans döneminden sonra önceki sırrı kaldırın. İmza doğrulamasını IP izin listesiyle değiştirmeyin: ağ kaynağı ve mesaj gerçekliği farklı sorunları çözer.

Alan taraf teslimat hatalarında ne yapmalı?

Bir webhook teslimat döngüsü 11 deneme içerir. Tekrar gecikmeleri bir dakikadan sekiz saate çıkar ve tam döngü yaklaşık 16 saat sürer. Başarısız veya ulaştırılamayan olaylar alan sistem toparlandıktan sonra elle yeniden oynatılabilir.

Yerel sipariş güncellemesini, aynı ödeme teslimatı iki kez tetikleyemeyecek şekilde kurun. Erişim vermeden, ürün göndermeden veya hesaba yazmadan önce kalıcı iş referansı kaydedin. Tekrarlanan bildirim mevcut sonucu bulmalı ve durmalıdır. Elle yeniden oynatma otomatik teslimatla aynı yolu izlemeli ki operatörler tekrar-güvenlik kuralını kazara atlamasın.

Sandbox testi nasıl organize edilmeli?

Sandbox, Production'da kullanılan aynı API yüzeyi üzerinden desteklenen ödeme ve çekim sonuçlarını simüle edebilir. Başarılı ödemeleri, başarısız ödemeleri, çekim sonuçlarını, imza doğrulamayı, tekrarlanan fatura oluşturmayı, teslimat toparlanmasını ve mutabakatı gerçek varlık taşımadan test etmek için kullanın.

Test fikstürlerini sabit external_order_id değerlerine bağlı tutun ki tekrarlanan test aynı iş siparişini anlatsın. Elle webhook yeniden oynatmasını çalıştırın ve teslimatın tek kaldığını doğrulayın. Ortam değiştirmeden önce servisin Production kimliklerini yalnızca Production sır deposundan okuduğunu ve yapılandırılmış test geri çağrı adresi kalmadığını doğrulayın.

Satıcı siparişi ne zaman teslim etmeli?

Ödeme geçerli onay politikasını karşıladıktan ve webhook imzası doğrulandıktan sonra teslim edin. Paymos onay gereksinimleri ağa ve ödeme tutarına bağlıdır. Küçük ödemeler daha az onay isteyebilir, büyük ödemeler daha güçlü kesinlik eşiği isteyebilir. Sabit hesaba geçme süresi bu yüzden entegrasyon sözleşmesinin parçası değildir. Onay rehberi alttaki risk modelini açıklar.

Teslimattan önce projenin eksik ödeme toleransını uygulayın. Yeni proje %0,1 ile açılır, aralık %0 ile %2 arasındadır ve %0 katı eşleşmedir. Yapılandırılan tolerans içindeki ödeme fiilen alınan tutarla tamamlanır; eksik kalan eklenmez. Eşiğin altında tek ödemeli fatura eksik ödenmiş olur, çoklu ödemeli fatura açık kalabilir.

Üretim sertleştirmesinde ne olmalı?

Ödeme, Ödeme Çıkışı, Sandbox ve Production kimliklerini ayrı tutun. Her webhooku HMAC-SHA256 ve zamanlama-güvenli karşılaştırmayla doğrulayın, güncel-önceki sır rotasyon tolerans dönemini planlayın ve teslimatı tekrar-güvenli yapın. 11 denemeli teslimat döngüsünü izleyin ve elle yeniden oynatma prosedürünü belgeleyin.

Genel webhook hedefi kullanın. Paymos loopback, özel, link-local, CGNAT ve IPv6 ULA adreslerini engeller ve otomatik HTTP yönlendirmelerini izlemez. Son olarak Paymos fatura durumunu satıcı sipariş sistemiyle mutabık tutun. Zaman aşımı, tekrarlanan oluşturma isteği, gecikmiş webhook, elle yeniden oynatma veya eksik ödeme yanlış sipariş sonucu üretemediğinde entegrasyon hazırdır.