Registrieren

Plugin-Entwicklung

Best Practices für die Entwicklung von E-Commerce-Plugins für zahls.ch.

Voraussetzungen

Bevor du startest, brauchst du Folgendes:

  • zahls.ch-Konto: Registrierung hier
  • Ein eingerichteter Zahlungsanbieter, der zu deinem Use Case passt: PSP-Funktionen
  • API-Zugangsdaten: In deinem zahls.ch-Konto unter API & Integration

Empfehlung

Plugin-Standards

Funktionen

Zahlungsmittel

Die Auswahl der Zahlungsmittel soll im Shopsystem erfolgen. Alle Zahlungsmittel sollten im Plugin einzeln aktivierbar sein.

Ist das nicht möglich, biete mindestens eine Icon-Auswahl, damit Händler Kunden zeigen können, welche Zahlungsmittel nach der Weiterleitung zu zahls.ch zur Verfügung stehen. Logos findest du in unserem Repository (kommerzielle Nutzung erlaubt):

https://github.com/payrexx/payment-logos

API-Zugangsdaten

Es soll möglich sein zu prüfen, ob Instanzname und API-Key korrekt gesetzt sind. Nutze dafür den Endpunkt Signatur Check.

Datenübermittlung

Übermittle so viele Daten wie möglich an zahls.ch.

So bleibt die Zuordnung zwischen zahls.ch-Transaktion und Shop-Bestellung erhalten und der Checkout wird für Endkunden einfacher. Manche Zahlungsmittel benötigen z. B. eine Adresse für Bonitätsprüfungen – Endkunden sollten diese nicht doppelt eingeben müssen.

Kurze Checkliste:

  • Pflichtdaten
    • Betrag (muss der Summe aller Warenkorbpositionen entsprechen!)
    • Währung
    • ReferenceId (Bestell-ID)
  • Kundendaten
    • E-Mail
    • Vollständiger Name und Adresse
  • Warenkorb
    • Produktnamen, SKU, Preis, Beschreibung
    • Versandkosten
    • Mögliche Rabatte
    • Mögliche Gebühren

Webhook

Jedes Plugin muss zahls.ch-Webhooks verarbeiten können, damit Transaktions- und Bestellstatus synchron bleiben.

Konfiguration

Jedes Plugin braucht Konfigurationsoptionen.

Pflichtangaben:

  • Instanzname (zahls.ch-Kontoname)
  • API-Key

Ohne diese Daten sind keine API-Anfragen möglich.

Zusätzliche Angaben:

  • Look & Feel ID
  • Prefix (wird der Referenz vorangestellt, um mehrere Shops zu unterscheiden)

Die Look & Feel ID steuert das Erscheinungsbild im Checkout – praktisch bei mehreren Webshops mit einem zahls.ch-Konto.

Zahlung

Der Kunde hat den Checkout abgeschlossen und möchte bezahlen.

Erstelle ein zahls.ch-Gateway und leite den Kunden zum Zahlungsformular weiter. Die vollständige Anleitung zum Gateway:

Gateway erstellen

Transaktions-Feedback

Der Shop muss jederzeit den Transaktionsstatus kennen – erfolgreich oder abgebrochen.

Das erreichst du mit zahls.ch-Webhooks: Bei jeder Statusänderung werden alle Transaktionsdaten an eine URL gesendet.

Details im Webhook-Guide:

Webhook

Weitere Informationen

Für einige Shopsysteme gibt es bereits Plugins. Der Quellcode ist Open Source und kann bei der Entwicklung helfen.

Shop-Plugins: