İçeriğe atlayın

Entegrasyonlar

Bu sayfada

Hosted Checkout

Müşterileri Hosted Checkout'a yönlendirin veya ödeme sayfasını kısıtlı bir iframe'e gömün, ardından siparişleri imzalı onay webhook'undan karşılayın.

POST /v1/invoices'un döndürdüğü payment_url değerini kanonik ödeme URL'si olarak kullanın. Aynı URL iki sunum modunu destekler — tam sayfa yönlendirme ve gömülü iframe.

Her iki mod da Telegram botu dışındaki tüm kanallarda çalışır. Telegram botu projesinde aynı payment_url Paymos botunu açar; yönlendirilecek ya da gömülecek barındırılan bir ödeme sayfası yoktur.

Yönlendirme modu

Yönlendirme modu en basit entegrasyondur. Sunucunuz faturayı oluşturduktan sonra müşteriyi payment_url adresine gönderin:

<a href="https://checkout.paymos.io/invoice/inv_xxx">Pay invoice</a>

Müşteri ödemeyi Paymos'un barındırdığı sayfada tamamlar. Sunucunuz siparişi yalnızca imzalı webhook olayını alıp doğruladıktan sonra karşılar.

Gömme modu

Gömme modu aynı payment_url'yi ?embed=true ile kullanır. Sunucunuz zaten fatura oluşturuyorsa ve yalnızca hosted checkout arayüzünü kendi sayfanızın içinde istiyorsanız bunu kullanın:

<iframe
  src="https://checkout.paymos.io/invoice/inv_xxx?embed=true"
  title="Paymos checkout"
  allow="clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms"
  style="display:block;width:100%;max-width:460px;height:min(90vh,900px);border:0;"
></iframe>

Gömme olayları

Checkout iframe'i, üst sayfaya postMessage taşıma olayları gönderir:

Olay Anlamı
paymos:succeeded Checkout paid veya paid_over durumuna ulaştı.
paymos:failed Checkout underpaid, expired veya cancelled gibi nihai bir başarısızlık durumuna ulaştı.
paymos:close Müşteri, gömülü checkout içinde bir kapat/geri eylemine tıkladı.

Üst sayfalar hem gönderen origin'i hem de iframe kaynağını doğrulamalıdır:

const iframe = document.querySelector('#paymos-checkout');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://checkout.paymos.io') return;
  if (event.source !== iframe.contentWindow) return;
  if (!event.data || typeof event.data !== 'object') return;

  switch (event.data.type) {
    case 'paymos:succeeded':
      console.log('Payment UI succeeded:', event.data.invoice_id);
      break;
    case 'paymos:failed':
      console.warn('Payment UI failed:', event.data.reason);
      break;
    case 'paymos:close':
      iframe.remove();
      break;
  }
});

Bu olayları ödeme kanıtı değil, UX ipucu olarak değerlendirin. Yüklenme göstergelerini, yönlendirmeleri ve analitiği bunlardan besleyin — ancak asla bir postMessage'a dayanarak ürün teslim etmeyin, bakiye yüklemeyin veya siparişi ödendi işaretlemeyin. Bir postMessage'ı taklit etmek son derece kolaydır: müşterinin origin'ini paylaşan herhangi bir sayfa sahte bir paymos:succeeded gönderebilir. Tahsilat yalnızca imzalı sunucu tarafı webhook ile onaylanır — teslimat için tek gerçek kaynak budur.

Güvenlik modeli

Önerilen iframe sandbox'ı kasıtlı olarak küçük tutulur:

  • —allow-scripts; checkout etkileşimi, API çağrıları, zamanlayıcılar, kopyalama düğmeleri ve canlı durum güncellemeleri için gereklidir.
  • —allow-same-origin, Paymos'un barındırdığı checkout'un opak bir sandbox origin'i yerine kendi origin'iyle çalışmasını sağlar.
  • —allow-forms, checkout içindeki normal form etkileşimlerine izin verir.
  • —allow-top-navigation atlanmıştır; böylece iframe işyeri sayfasını yönlendiremez.
  • —allow-popups atlanmıştır; çünkü checkout'un ek tarayıcı penceresi açması gerekmez.

Ne zaman Low-Code SDK kullanılmalı

Paymos'un tarayıcı tarafı yapılandırmadan fatura oluşturmasını, ödeme düğmesini çizmesini, modal yaşam döngüsünü yönetmesini, iframe mesajlarını doğrulamasını ve sizin için paymos:* CustomEvent'lerini tetiklemesini istiyorsanız Low-Code SDK kullanın.

Arka ucunuz fatura oluşturmayı zaten üstlenmişse ve yalnızca hosted checkout arayüzünü sayfanızın içine yerleştirmeniz gerekiyorsa manuel iframe gömmeyi kullanın.

PrestaShop Eklentisi JavaScript Low-Code SDK