Zum Inhalt springen

Integrationen

Auf dieser Seite

Gehosteter Checkout

Auf den gehosteten Checkout weiterleiten oder die Zahlungsseite als Iframe einbetten und Bestellungen erst nach dem signierten Bestätigungs-Webhook ausführen.

Nutzen Sie die von POST /v1/invoices zurückgegebene payment_url als kanonische Checkout-URL. Dieselbe URL unterstützt zwei Darstellungsarten — Weiterleitung auf die volle Seite und eingebettetes Iframe.

Beide Darstellungsarten gelten für jeden Kanal außer Telegram-Bot. Dort öffnet dieselbe payment_url den Paymos-Bot — eine gehostete Seite, die sich weiterleiten oder einbetten ließe, gibt es nicht.

Weiterleitung

Die Weiterleitung ist die einfachste Anbindung. Schicken Sie den Kunden auf die payment_url, nachdem Ihr Server die Rechnung erstellt hat:

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

Der Kunde schließt die Zahlung auf der von Paymos gehosteten Seite ab. Ihr Server führt die Bestellung erst aus, nachdem er das signierte Webhook-Ereignis empfangen und geprüft hat.

Einbettung

Die Einbettung nutzt dieselbe payment_url mit ?embed=true. Verwenden Sie sie, wenn Ihr Server Rechnungen bereits erstellt und Sie nur die Oberfläche des gehosteten Checkouts in Ihrer eigenen Seite haben möchten:

<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>

Ereignisse der Einbettung

Das Checkout-Iframe sendet Transport-Ereignisse per postMessage an die übergeordnete Seite:

Ereignis Bedeutung
paymos:succeeded Der Checkout hat paid oder paid_over erreicht.
paymos:failed Der Checkout hat einen Endzustand mit Fehlschlag erreicht, etwa underpaid, expired oder cancelled.
paymos:close Der Kunde hat im eingebetteten Checkout auf Schließen oder Zurück geklickt.

Die übergeordnete Seite muss sowohl die Herkunft des Absenders als auch die Quelle des Iframes prüfen:

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;
  }
});

Behandeln Sie diese Ereignisse als Hinweise für die Oberfläche, nicht als Zahlungsnachweis. Steuern Sie damit Ladeanzeigen, Weiterleitungen und Auswertung — aber liefern Sie niemals Ware aus, schreiben Sie kein Guthaben gut und markieren Sie keine Bestellung als bezahlt aufgrund eines postMessage. Ein postMessage lässt sich trivial fälschen: Jede Seite mit derselben Herkunft wie der Kunde kann ein falsches paymos:succeeded senden. Die Abrechnung bestätigt allein der signierte serverseitige Webhook — die einzige verlässliche Quelle für die Auslieferung.

Sicherheitsmodell

Die empfohlene Sandbox für das Iframe ist bewusst knapp gehalten:

  • —allow-scripts ist nötig für die Interaktivität des Checkouts, API-Aufrufe, Timer, Kopier-Buttons und Statusaktualisierungen in Echtzeit.
  • —allow-same-origin lässt den von Paymos gehosteten Checkout mit eigener Herkunft laufen statt in einer undurchsichtigen Sandbox-Herkunft.
  • —allow-forms erlaubt normale Formularinteraktionen im Checkout.
  • —allow-top-navigation fehlt bewusst, damit das Iframe die Händlerseite nicht wegnavigieren kann.
  • —allow-popups fehlt, weil der Checkout keine zusätzlichen Browserfenster öffnen muss.

Wann stattdessen das Low-Code SDK

Nutzen Sie das Low-Code SDK, wenn Paymos Rechnungen aus einer Konfiguration im Browser erstellen, den Bezahl-Button darstellen, den Lebenszyklus des Overlays verwalten, Iframe-Nachrichten prüfen und paymos:*-CustomEvents für Sie auslösen soll.

Nutzen Sie die manuelle Iframe-Einbettung, wenn Ihr Backend die Rechnungserstellung bereits besitzt und Sie nur die Oberfläche des gehosteten Checkouts in Ihrer Seite platzieren möchten.

PrestaShop Plugin JavaScript Low-Code SDK