Ödeme ağ geçidi entegrasyonu

Kullanılabilirliği kontrol etme#

Kevmi, ağ geçidi v3 API'sini işlemler oluşturmak ve kurtarmak, durumları okumak ve sonuçları mutabakat sağlamak için kullanır. Entegrasyon, şifreli kart ve banka kodu iletimini, Alipay ve SBP QR ödemelerini, bir kripto para/şebeke kataloğunu ve gelen finansal olayları destekler.

gateway.configured GET /api/config içinde gerekli bağlantı ayarlarının mevcut olup olmadığını bildirir. Bu uç nokta ağ geçidini yoklamaz; gateway.connected=false burada bağlantının doğrulanmadığı anlamına gelir. Belirli bir fatura için, GET /api/checkout/{token} içinde invoice.availability okuyun: yöntemi, tutarı, koşulları ve satıcı onayını kontrol eder. invoice.gatewayConnected uyumluluk alanı availability.available'ı yansıtır ve ne bir sağlık kontrolü ne de ödeme onayının garantisidir.

Yeni bir ödeme ve kart niyeti, satıcının en son web sitesi inceleme başvurusunun onaylanmasını gerektirir. Onay tek başına ödeme ağ geçidini bağlamaz. İnceleme gönderimden sonra değişirse, mevcut işlem durum okumaları, mutabakat ve talep edilen banka kodu için kullanılabilir kalır.

Müşteri ödeme sözleşmesi#

Hassas veriler tarayıcıda RSA-OAEP-256 ve A256GCM ile şifrelenir. Özel anahtar ağ geçidinde kalır. Kevmi niyetin bu faturaya ve amaca ait olduğunu doğrular, zarfı iletir ve düz metin kart numaralarını, CVV'yi, alıcı adını, e-postayı, banka kodlarını veya zarfın kendisini saklamaz.

Kartları etkinleştirmeden önce şifreli iletim uzantısını ağ geçidi ana bilgisayarına kurun. Niyet imzasını, süre sonunu, tekrar oynatmayı, siparişi ve tutarları kontrol eder. Düz metin geri dönüşü yoktur. Bu koruma mekanizmasını açıklar, PCI sertifikasını değil.

Barındırma ve ağ geçidi bağlantısı#

Kevmi, Cloudflare Workers üzerinde D1 ile Sites barındırma ve Node.js üzerinde SQLite ile kendi kendine barındırmayı destekler. SQLite kalıcı bir birim ve yedekleme gerektirir. Ödeme ağ geçidi, kendi kalıcı depolama alanıyla ayrı bir hizmet olarak çalışır.

Harici bir ağ geçidi, sunucunun erişebileceği bir HTTPS kaynağı gerektirir. Kendi kendine barındırılan pakette, sunucu özel konteyner ağında sabit bir ağ geçidi hizmetine bağlanır; ağ geçidi hizmet API'si internete açık değildir. Genel site ve geri çağrılar HTTPS kullanır. Tarayıcı ayrıca kart ayrıntılarını ve banka kodlarını Kevmi'ye ulaşmadan önce şifreler.

localhost geçerli sunucu veya konteyneri ifade eder; ağ geçidi sahibinin bilgisayarını açığa çıkarmaz. Bağlantı anahtarları ve sırlar yalnızca sunucu yapılandırmasında bulunur.

Özel bir alan adı için, derlemeden önce NEXT_PUBLIC_SITE_URL içinde genel bir HTTPS kaynağı ayarlayın. Dokümantasyon, kanonik bağlantılar ve dizinleme kaynakları bu değeri kullanır. Yalnızca şema ve isteğe bağlı bağlantı noktası olan bir ana bilgisayar kabul eder; yol, sorgu, parça veya kimlik bilgileri olmadan. Bunu sunucu yapılandırmasındaki APP_ORIGIN ile eşleştirin.

Hesaplama ve desteklenen koşullar#

Yeni çalışma alanı faturaları USD taban fiyat kullanır ve Any dört yöntemin tümünü sunar. SBP, donmuş Rusya Merkez Bankası referans kuru üzerinden RUB'a çevrilir; kripto, açık 1:1 USD/USDT fatura kuralını kullanır. Eski yerel fiyatlandırma, eski faturalar ve pricingMode=universal olmayan API istekleri için kullanılabilir durumda kalır. Aşağıdaki çoklu mağaza ve USD fiyatlandırma bölümüne bakın.

Yeni bir canlı kart veya Alipay ödemesi için mevcut ağ geçidi yalnızca feeCustomerPercent=0 ve vatCustomerPercent=100'ü destekler: satıcı tüm işlem ücretini karşılar ve KDV müşteri için tam olarak eklenir. Diğer paylar bir faturada kaydedilip hesaplanabilir, ancak yürütme unsupported_allocation ile engellenir. Sunucu kaydedilmiş koşulları sessizce asla değiştirmez. SBP ve USDT kripto ödemeleri tüm işlem ücreti paylarını destekler ve KDV içermez.

Rastgele bir total_cents göndermek sağlayıcının vergi hesaplamasını değiştirmez. Kaydedilen toplamdan farklı olan gerçek bir tutar incelemeye girer ve yerine getirmeyi onaylayamaz. Ağ geçidi business_balance alanları, Kevmi tüccar bakiyesi olarak değil, uzlaşma kanıtı olarak saklanır.

Canlı bir ağ geçidi bağlama#

Ağ geçidini bağlamak sunucu yapılandırması, seçilen kanallar için kontroller ve doğrulanmış finansal olayların işlenmesini içerir. Yapılandırma hazırlığı, sağlayıcı bağlantısından ayrı olarak kontrol edilir. Başarılı bir ödeme, işlem durumu ve tutarı doğrulandıktan sonra kabul edilir. Dağıtım talimatları ops/gateway-integration.md içindedir.

1. 1

   Kevmi sunucusunu ve ağ geçidini ayrı hizmetler olarak dağıtın. Kalıcı depolama, yedeklemeler ve gerekli arka plan işlemlerini yapılandırın.

2. 2

   Harici bir bağlantı için GATEWAY_BASE_URL içinde bir HTTPS kaynağı ayarlayın. Kendi kendine barındırılan paket, yapılandırılmış dahili hizmetini kullanır. Her ikisi de yalnızca sunucuya özel bir GATEWAY_API_KEY ve ayrı bir GATEWAY_WEBHOOK_SECRET gerektirir; sırlar asla tarayıcıya ulaşmaz.

3. 3

   Ağ geçidi BACKEND_WEBHOOK_URL'yi Kevmi'de /api/gateway/webhook olarak ve eşleşen bir BACKEND_WEBHOOK_SECRET ayarlayın.

4. 4

   Şifrelenmiş kart taşımacılığını etkinleştirin ve özel anahtarını yalnızca ağ geçidi ana bilgisayarında tutun. Genel anahtar kullanılabilirliğini ve eşleşen niyet imzalama ayarlarını kontrol edin.

5. 5

   Başlatmadan önce kanal hazırlığını, kısıtlamaları ve tüccar web sitesi onayını kontrol edin.

Birden fazla mağaza ve tek USD taban fiyat#

Toplu analiz ve işlemler için Tüm mağazaları seçin veya kendi kayıtları için bir mağaza seçin. Her mağazanın ayrı bir storeId'si, adı, varsayılan KDV'si, faturaları, API anahtarları, webhook uç noktaları, olay geçmişi ve web sitesi uygulaması vardır. Bildirimler ve destek talepleri hesaba aittir. Bir hesap en fazla 100 mağaza oluşturabilir. Mevcut kayıtlar ilk mağazasında kalır.

Yeni çalışma alanı faturaları pricingMode="universal" ve USD taban fiyat kullanır. Any, kart, alipay, sbp ve kriptoyu içerir; bir satıcı bir alt küme seçebilir. Kartlar ve Alipay USD tahsil eder. SBP, Rusya Merkez Bankası USD/RUB referans kurunu kullanarak RUB tahsil eder. Kripto, açık fatura kuralı 1 USD = 1 USDT kapsamında USDT tahsil eder. Bu bir fatura dönüştürme kuralıdır, piyasa USDT kotasyonu değildir. Ağ geçidi, transferden önce seçilen coin'in kurunu, tam transfer tutarını ve talimatlarını sağlar.

Referans kuru ve her iki tutar oluşturma sırasında dondurulur. RUB dönüştürmesi içeren faturalar 24 saat içinde sona erer. Referans kuru alınamazsa, oluşturma FX_UNAVAILABLE ile başarısız olur; uydurulmuş veya bayat yedek kur kullanılmaz. Sahip yanıt tutarı ve kotasyonlar USD muhasebe para birimini kullanır. quotes[method].settlement, yerel tahsil kotasyonunu içerir. Genel ödeme sayfası, seçilen tahsil para birimini currency içinde, orijinal fiyatı baseAmountMinor/baseCurrency içinde ve referans kurunu fx içinde gösterir. Bir ödeme gönderildikten sonra yöntemi değiştirilemez; bir faturanın tek ağ geçidi işlemi vardır.

Amaçlanan mağaza içinde bir API anahtarı oluşturun ve sunucunuzdan Authorization: Bearer <key> gönderin. Mağaza bağlaması değişmezdir; X-Kevmi-Store, anahtara başka bir mağazaya erişim izni veremez. Tarayıcı oturumları X-Kevmi-Store: <storeId> seçer; atlanırsa ilk mağaza seçilir. all değeri yalnızca GET /api/account/dashboard ve GET /api/payment-links tarafından kabul edilir. Değişiklikler seçili bir mağaza, Origin ve X-CSRF-Token gerektirir. Hesap kimlikleri ve mağaza kimlikleri farklı tanımlayıcılardır.

Uyumluluk için, pricingMode="universal" içermeyen API istekleri yerel fiyatlandırmayı ve orijinal para birimi kısıtlamalarını korur. Mevcut faturalar asla yeniden hesaplanmaz. Analizlerdeki onaylanmış tahsilatlar, doğrulanmış ödemelerden kaydedilmiş fatura giderlerinin düşülmesiyle elde edilir; bunlar çekilebilir bakiye değildir. Eski fatura para birimleri ayrı kalır ve ödemeler destek ile düzenlenir. Bir siparişi yalnızca sunucu API'si, olay geçmişi veya imzalı bir webhook üzerinden payment.fulfillmentReady=true ve payment.status="succeeded" durumunu kontrol ettikten sonra yerine getirin.