JavaScript Low-Code SDK

Low-Code SDK, web sitenize doğrudan bir ödeme düğmesi gömmenizi sağlar. Müşteri tıkladığında SDK ödeme tutarını çözer, herkese açık SDK anahtarınızla (pk_...) bir fatura oluşturur ve ödeme formunu açar — iframe modalı veya tam sayfa yönlendirme olarak.

Low-Code SDK, POST /v1/invoices çağrısının payment_url olarak döndürdüğü aynı barındırılan ödeme sayfasının üzerinde bir kolaylık sarmalayıcısıdır; iframe modunda o ödeme sayfasını ?embed=true ile açar. Ham yönlendirme ve manuel iframe sözleşmesi için bkz. Barındırılan Ödeme Sayfası.

SDK, arka planda paymos-widget.js dosyasını sunan aynı origin'e — https://paymos.io/public/v1/sdk — anahtarınız X-Sdk-Key başlığında olacak şekilde istek gönderir.

Tutar yoksa ve bir pos_url verdiyseniz düğme bunun yerine o Terminal sayfasını açar — tutarın elle girildiği bir sayısal tuş takımı. pos_url olmadan, çözülebilir tutarı olmayan bir tıklama hata fırlatır ve paymos:error yayar.

Nasıl çalışır

• 01SDK betiğini ve bir bağlama noktasını sayfanıza ekleyin
• 02PaymosWidget.mount() çağrısını api_key, project_id ve seçeneklerinizle yapın
• 03Müşteri düğmeye tıklar
• 04SDK tutarı çözer (sabit değer, geri çağırma veya input seçici)
• 05Tutar varsa — SDK bir fatura oluşturur ve ödeme sayfasını açar
• 06Tutar yoksa ve pos_url ayarlıysa — SDK o URL'deki Terminal tuş takımını açar
• 07Tutar ve pos_url yoksa — SDK hata fırlatır ve paymos:error yayar
• 08Ödeme işlenir — kayıtlı webhook URL'nize webhook gönderilir

Kurulum

<script src="https://paymos.io/v1/paymos-widget.js"></script>
<div id="paymos-widget"></div>

Tutarın çözülmesi

SDK, düğmeye tıklandığı anda ilk kullanılabilir kaynağı kullanarak ödeme tutarını çözer:

• 01amount — yapılandırmada verilen sabit ondalık dize. Tek ürünlü sayfalar veya sabit fiyatlı öğeler için idealdir.
• 02get_amount() — tutarı ondalık dize olarak döndüren bir geri çağırma fonksiyonu. Toplam dinamik hesaplandığında (ör. alışveriş sepetinden) bunu kullanın.
• 03amount_selector — bir <input> öğesini işaret eden CSS seçici. SDK tıklama anında .value değerini okur. Müşteri tutarı kendisi yazdığında kullanışlıdır.

Yukarıdakilerden hiçbiri geçerli bir pozitif ondalık dize döndürmezse SDK, pos_url adresinizdeki Terminal'i açar — tutarın elle girildiği bir tuş takımı. pos_url ayarlamadıysanız tıklama PaymosWidget requires an amount, amountSelector, or price_id. hatası fırlatır ve ödeme sayfası açılmaz.

// Fixed price (price_id) — RECOMMENDED for fixed products.
// Create the price once in the dashboard; the server resolves the amount and
// currency from it, so a buyer cannot change them in DevTools. No amount in the embed.
PaymosWidget.mount('#paymos-widget', {
  api_key: 'YOUR_PUBLIC_KEY',
  price_id: 'price_YOUR_PRICE_ID'
});

// Fixed amount — client-supplied (editable in the browser; use for donations / free-amount)
PaymosWidget.mount('#paymos-widget', {
  api_key: 'YOUR_PUBLIC_KEY',
  project_id: 'prj_YOUR_PROJECT_ID',
  amount: '25.00',
  currency: 'USD'
});

// Dynamic amount — computed at click time
PaymosWidget.mount('#paymos-widget', {
  api_key: 'YOUR_PUBLIC_KEY',
  project_id: 'prj_YOUR_PROJECT_ID',
  get_amount: () => calculateCartTotal().toFixed(2),
  currency: 'USD'
});

// Input selector — reads value from an <input> element
PaymosWidget.mount('#paymos-widget', {
  api_key: 'YOUR_PUBLIC_KEY',
  project_id: 'prj_YOUR_PROJECT_ID',
  amount_selector: '#donation-amount',
  currency: 'USD'
});

İki entegrasyon modu

SDK iki giriş noktası sunar. Sayfanıza uyanı seçin:

mount(selector, opts) — SDK düğmeyi çizer

SDK, hedef öğeye tam stillendirilmiş, kullanıma hazır bir Öde düğmesi enjekte eder (metni label seçeneğinden gelir, varsayılan "Support with crypto"). Tek ürünlü sayfalar, basit açılış sayfaları, bağış bileşenleri için idealdir — sıfır CSS işi istediğiniz her yerde.

<script src="https://paymos.io/v1/paymos-widget.js"></script>
<div id="paymos-widget"></div>
<script>
  PaymosWidget.mount('#paymos-widget', {
    api_key: 'pk_live_…',
    project_id: 'prj_…',
    amount: '25.00',
    currency: 'USD',
    label: 'Support with crypto'
  });
</script>

open(opts) — düğmeyi siz çizersiniz, SDK katmanı açar

Düğme DOM'unun tam kontrolü sizde kalır (kendi tasarım sisteminiz, CSS'iniz, simgeleriniz) ve bir tıklama işleyicisinden PaymosWidget.open(opts) çağırırsınız. Birden fazla planlı fiyatlandırma sayfaları, alışveriş sepetleri, özel UI çatıları (React, Vue, Svelte bileşenleri) için idealdir.

<button id="buy-growth">Subscribe to Growth — $79/mo</button>
<script>
  document.getElementById('buy-growth').addEventListener('click', function () {
    PaymosWidget.open({
      api_key: 'pk_live_…',
      project_id: 'prj_…',
      amount: 79,
      currency: 'USD',
      client_id: 'plan:growth'
    });
  });
</script>

İki mod da aynı arka uca gider, aynı webhook'ları tetikler ve aynı pencere olaylarını yayar. Seçim tamamen düğme stillendirme sorumluluğuyla ilgilidir — open(), Panel'deki Open Demo bağlantısının başlattığı şeydir (tek paylaşımlı katman üzerinden yönlendirilen üç bağımsız stillendirilmiş düğmeli bir fiyatlandırma sayfası).

SDK ve REST API ne zaman

Low-Code SDK bir tarayıcı tarafı araçtır — arka uç olmadan statik bir HTML sayfasına Öde düğmesi koyar. Şunlar için mükemmeldir:

• Bağış / bahşiş kavanozları (tutarı müşteri seçer)
• POS / kasiyer yönetimli akışlar (tutarı personel yazar)
• Serbest tutarlı bileşenler ("fiyatı siz belirleyin")
• Dahili sandbox / staging demoları

Yapılandırma

Parametre	Tip	Zorunlu	Açıklama
api_key	string	Evet	Panel'den alınan herkese açık SDK anahtarı (pk_...)
project_id	string	price_id verilmedikçe evet	Proje kimliği (prj_...)
price_id	string	Hayır	Panel'de oluşturulan sabit fiyat (price_...). Sunucu tutar ve para birimini ondan çözer; böylece alıcı bunları düzenleyemez — sabit ürünler için önerilir. Aşağıdaki her tutar kaynağının önüne geçer
amount	string | number	Hayır	Ondalık dize veya sayı olarak sabit ödeme tutarı
get_amount	function	Hayır	Tıklama anında tutarı ondalık dize olarak döndüren geri çağırma
amount_selector	string	Hayır	Tutarı içeren input'un CSS seçicisi
currency	string	Hayır	Fiat para birimi kodu (USD, EUR vb.). Varsayılan: USD
client_id	string	Hayır	Dahili müşteri kimliğiniz (faturaya eklenir)
mode	string	Hayır	"iframe" (varsayılan) — modal katman. "redirect" — tam sayfa gezinme
label	string	Hayır	Düğme metni. Varsayılan: "Support with crypto"
width	string	Hayır	"auto" (varsayılan) veya %100 genişlik için "full"
accent_color	string	Hayır	Düğme vurgu rengi (hex). Varsayılan: #ff6b35
text_color	string	Hayır	Düğme metin rengi (hex). Varsayılan: #ffffff. Kontrast denetimi yalnızca kendi accent_color değerinizi de verdiğinizde çalışır: renginiz ona karşı 4.5 'i geçiyorsa SDK onu korur, geçmiyorsa ölçülen kontrasta göre siyah ya da beyaz seçer. Varsayılan vurgu renginde denetim yapılmaz, verdiğiniz değer aynen kalır
radius	number	Hayır	Düğme köşe yarıçapı, 0-32 px. Varsayılan: 18
frame_title	string	Hayır	iframe öğesi için erişilebilir başlık. Varsayılan: "Paymos checkout"
aria_label	string	Hayır	Modal iletişim kutusu için erişilebilir ad. Varsayılan: "Paymos checkout"
pos_url	string	Hayır	POS/Terminal sayfanızın URL'si. Ayarlandığında, tutar çözülemezse düğme Terminal'i açar
target	string	Hayır	"_self" (varsayılan) veya "_blank" (yalnızca redirect modu)
auto_close_delay	number	Hayır	Modal kendini kapatmadan önce başarı ekranının görünür kalacağı milisaniye. Varsayılan: 0 (kapalı). Modal içindeki herhangi bir kullanıcı etkileşimiyle iptal edilir.
haptics	boolean	Hayır	Destekleyen platformlarda kısa dokunsal geri bildirimi etkinleştirir (Android, bazı PWA'lar). iOS Safari Vibration API'yi yok sayar — orada işlemsizdir. prefers-reduced-motion değerine uyar. Varsayılan: true
timeout	number	Hayır	Fatura oluşturma isteği iptal edilmeden önceki milisaniye. Değerler pozitif olmalıdır; diğer her şey varsayılan değere döner. Varsayılan: 30000
debug	boolean	Hayır	Yalnızca mesaj yerine tam Error nesnelerini konsola kaydeder. Varsayılan: false

Tam örnek

<script src="https://paymos.io/v1/paymos-widget.js"></script>

<div id="paymos-widget"></div>

<script>
  PaymosWidget.mount('#paymos-widget', {
    api_key: 'YOUR_PUBLIC_KEY',
    project_id: 'prj_YOUR_PROJECT_ID',
    amount: '25.00',
    currency: 'USD',
    label: 'Support with crypto',
    mode: 'iframe',
    accent_color: '#FF6B35',
    text_color: '#FFFFFF',
    radius: 20
  });
</script>

Programatik API

Ödeme sayfasını düğme bağlamadan da açabilirsiniz:

// Open checkout programmatically (no button)
await PaymosWidget.open({
  api_key: 'YOUR_PUBLIC_KEY',
  project_id: 'prj_YOUR_PROJECT_ID',
  amount: '50.00',
  currency: 'USD',
  mode: 'iframe'
});

// Close the modal
PaymosWidget.close();

// Remove the button and clean up
PaymosWidget.destroy('#paymos-widget');

Olaylar

SDK, sayfanızın ödeme yaşam döngüsüne tepki verebilmesi için window üzerinde CustomEvent'ler yayar. Tüm yükler event.detail üzerindedir.

Olay	Ne zaman tetiklenir	event.detail
paymos:opened	Modal bağlandı ve iframe URL'si ayarlandı.	{ url }
paymos:closed	Modal kaldırıldı (isteğe bağlı auto_close_delay zamanlayıcısının tetiklenmesi dahil her neden).	{ reason: 'escape' | 'iframe' | 'replaced' | 'api' | 'success' }
paymos:succeeded	Müşterinin ödemesi paid veya paid_over durumuna ulaştı. iframe içinden postMessage ile yayılır.	{ invoiceId }
paymos:failed	Nihai başarısızlık durumu (underpaid, expired, cancelled).	{ invoiceId, reason }
paymos:error	SDK faturayı bile oluşturamadı (ağ/kimlik/CORS/zaman aşımı).	{ message }

succeeded / failed olayları yalnızca ödeme iframe modunda açıldığında tetiklenir — ödeme sayfasının window.parent.postMessage çağırmasıyla teslim edilir. SDK bir mesajı yalnızca gömdüğü ödeme URL'sinin origin'inden ve yalnızca o iframe'in kendi contentWindow'undan kabul eder; böylece satıcı sayfasındaki hiçbir üçüncü taraf bunları taklit edemez.

Redirect modundaki ödemelerde sayfa sonuç bilinmeden önce gezinir; tahsilatı doğrulamak için sunucunuzda webhook kullanın.

// 1. The customer paid — auto-close the modal and redirect to a thank-you page.
window.addEventListener('paymos:succeeded', (e) => {
  console.log('Paid:', e.detail.invoiceId);
  PaymosWidget.close();
  // Absolute and on your own domain: a root-relative path in a published
  // code sample gets crawled as one of OUR URLs — Googlebot did exactly that
  // and filed /thank-you?order= as a 404 against paymos.io.
  window.location.href = 'https://your-shop.example/thank-you?order=' + e.detail.invoiceId;
});

// 2. Payment failed (underpaid / expired / cancelled).
window.addEventListener('paymos:failed', (e) => {
  console.warn('Payment failed:', e.detail.invoiceId, e.detail.reason);
  // e.detail.reason: 'underpaid' | 'expired' | 'cancelled'
});

// 3. Modal lifecycle.
window.addEventListener('paymos:opened',  (e) => console.log('Opened',  e.detail.url));
window.addEventListener('paymos:closed',  (e) => console.log('Closed',  e.detail.reason));
//   e.detail.reason: 'escape' | 'iframe' | 'replaced' | 'api' | 'success'

// 4. Invoice creation failed (network down, bad config, server error).
window.addEventListener('paymos:error', (e) => {
  console.error('SDK error:', e.detail.message);
});

İzin verilen origin

SDK yalnızca bileşen ayarlarınızda yapılandırılan Allowed Origin ile eşleşen alan adlarında çalışır. Diğer origin'lerden gelen istekler reddedilir.

Terminal geri dönüşü

Geri dönüş isteğe bağlıdır: pos_url değerini Terminal sayfanıza yönlendirin. Geçerli tutar çözülemediğinde (amount yok, get_amount() null döndürüyor veya amount_selector input'u boş), SDK o URL'yi açar — tutarın elle girildiği bir tuş takımı. Toplamın işlem başına değiştiği satış noktası senaryoları için kullanışlıdır.

pos_url ayarlanmamışsa aynı durum bunun yerine PaymosWidget requires an amount, amountSelector, or price_id. hatası fırlatır ve sayfanıza paymos:error olayı olarak ulaşır.