Dokumentation
Dokumentation
Zahlungslinks

1Was sind Zahlungslinks?

Zahlungslinks helfen dabei, Zahlungen zu erfassen, wenn auf der Händlerseite kein Backend / Shop für die Verarbeitung der Zahlungen verfügbar ist. Zahlungslinks ermöglichen es Ihnen als Händler daher, Zahlungen ohne jegliche serverseitige Programmierung zu erfassen. Die Zahlung wird durch den Aufruf einer URL mit bestimmten Parametern erstellt. Bei den Parametern handelt es sich um reguläre HTTP-GET- oder POST-Parameter. Zum Beispiel: Die Rechnungsadresse wird aus den Parametern der HTTP-Anfrage an die URL übernommen.

Die Zahlungslinks können für eine Vielzahl von Anwendungsfällen genutzt werden. Die folgende, nicht abschliessende Liste zeigt einige Anwendungsfälle:

  • Wenn Sie ein einfaches Produkt auf Ihrer Website verkaufen möchten, aber kein Backend implementieren und keinen Warenkorb für Produktverwaltung oder Lagerverwaltung verwenden möchten, können Sie diese Zahlungslinks nutzen. Dies kann eine sehr gute Lösung sein, um Flash-Sales abzuwickeln, bei denen Sie keinen Shop erstellen möchten, statische Content-Websites usw. Wenn Sie Zahlungslinks verwenden, können Sie ein einfaches HTML-Formular auf Ihrer Website platzieren, das auf unsere Plattform verweist, welche die Zahlung verarbeitet und die Rechnungsdaten prüft. Zusätzlich können Sie für dieses bestimmte Produkt ein Limit für die Anzahl der Käufe festlegen. Das Produkt und alle Versandkosten können im Zahlungslink vordefiniert werden. Alle Bestätigungs-E-Mails können von unserem System versendet werden.

  • Wenn Sie auf Ihrer Website Spenden sammeln möchten, können Sie ein einfaches Formular auf Ihrer Website platzieren, das auf unsere Plattform verweist. Der Betrag kann dynamisch im Formular auf Ihrer Website festgelegt werden. Sie können beliebige Kontaktdaten erfassen und diese Daten auf Wunsch in unserem System speichern. Alle E-Mails werden von unserem System versendet. Sie können sie nach Belieben anpassen und individualisieren.

Note
 Bitte verwenden Sie Charge Flows, wenn Sie Zahlungen per E-Mail erfassen möchten und sich nicht um den Versand mehrerer E-Mails und die Verwaltung verschiedener Mahnstufen kümmern möchten, wenn Ihr Kunde nicht auf den Link klickt.

2Wie kann ich einen Zahlungslink einrichten?

Gehen Sie zu Space > Zahlungslinks > Erstellen und geben Sie die erforderlichen Daten an. Wenn Sie zahlreiche Zahlungslinks automatisiert einrichten müssen, sollten Sie die Verwendung des Zahlungslink-Webservice in Betracht ziehen.

Für die Erstellung des Zahlungslinks ist ein Name erforderlich, da dieser in der Administrationsoberfläche angezeigt wird. Alle weiteren zusätzlichen Angaben sind optional. Wenn Sie diese Angaben jedoch nicht machen, können sie vom Benutzer verändert werden. Wenn Sie also die Zahlungen nur in einer bestimmten Währung erfassen möchten, müssen Sie diese Angabe machen. Andernfalls übernehmen wir die Währung, die Sie in der Anfrage an die URL angegeben haben. Dasselbe gilt auch für die Positionen: Werden sie nicht angegeben, übernehmen wir die in der Anfrage angegebenen.

Note
 Die Anfrage kann vom Käufer verändert werden, und der belastete Betrag kann von dem abweichen, was Sie beabsichtigt haben.

3Wie kann ich einen Zahlungslink verwenden? Wie kann ich ihn in meine Website integrieren?

Sobald Sie einen Zahlungslink erstellt haben, können Sie die bereitgestellte URL übernehmen und aufrufen. Je nachdem, wie Sie den Zahlungslink eingerichtet haben, müssen Sie in der Anfrage, welche die Zahlungslink-URL aufruft, zusätzliche Parameter angeben.

Wenn Sie ihn über ein Formular auf Ihrer Website aufrufen möchten, können Sie das so tun:

<form action="<< put here payment link url >>" method="POST">

	<input type="text" name="billingAddress[givenName]" placeholder="Given Name" />
	<input type="text" name="billingAddress[familyName]" placeholder="Family Name" />
	<input type="text" name="billingAddress[street]" placeholder="Street" />
	<input type="text" name="billingAddress[postcode]" placeholder="Postcode" />
	<input type="text" name="billingAddress[city]" placeholder="City Name" />
	<input type="text" name="billingAddress[country]" placeholder="Country Code" />

	<input type="hidden" name="lineItems[0][uniqueId]" value="test" />
	<input type="hidden" name="lineItems[0][sku]" value="test" />
	<input type="hidden" name="lineItems[0][name]" value="Test" />
	<input type="hidden" name="lineItems[0][amountIncludingTax]" value="10.87" />
	<input type="hidden" name="lineItems[0][type]" value="PRODUCT" />
	<input type="hidden" name="lineItems[0][quantity]" value="1" />

	<input type="hidden" name="metaData[additionalData]" value="Further data you want to store along the transaction." />

	<input type="hidden" name="currency" value="CHF" />

	<!-- Further parameters as you need. -->

	<input type="submit" value="Pay" />
</form>

Wir empfehlen, die method POST und nicht GET zu verwenden, da die Formularparameter sonst an die URL angehängt werden. Die URL darf nicht länger als 2000 Zeichen sein, da einige Browser dies nicht unterstützen. Mit POST vermeiden Sie solche Probleme.

4Welche Parameter kann ich senden?

Im Wesentlichen können Sie jeden Parameter senden, den Sie über die Webservice-API senden können, wenn Sie eine Transaktion erstellen. Im Grunde muss das JSON in ein Format überführt werden, das von regulären HTML-Formularen erzeugt werden kann. Die Daten müssen in UTF-8-Kodierung übertragen werden. Wir beschreiben die Parameter und ihr Format nachfolgend:

4.1Rechnungsadresse und Lieferadresse

Die Rechnungs- und die Lieferadresse haben dieselben Felder. Wenn eine Adresse angegeben wird, prüfen wir, ob ein minimaler Satz von Feldern angegeben ist, der eine Zustellung ermöglicht. Die erforderlichen Parameter und ihr Format hängen vom Land ab. Nachfolgend finden Sie eine Liste aller Felder, die für eine Adresse erforderlich sind:

  • country: Der zweistellige Ländercode nach ISO 3166-1 bestimmt, wie die Adresse validiert wird.

  • givenName: Der Vorname enthält den Vornamen des Kunden.

  • familyName: Der Nachname enthält den Nachnamen des Kunden.

  • street: Der Strassenname einschliesslich Hausnummer usw. der Adresse.

  • postCode: Die Postleitzahl der Adresse ist normalerweise erforderlich.

  • city: Der Name der Stadt ist normalerweise ebenfalls erforderlich.

Weitere Informationen darüber, welche Felder ausserdem verfügbar sind und wie wir sie validieren, finden Sie auch in der Adressmodell-Definition.

Um die Adressvalidierung zu vereinfachen, können Sie unsere JavaScript-Bibliothek einbinden, mit der die Adresse direkt auf Ihrer Website validiert werden kann. Werfen Sie dazu einen Blick in die Dokumentation zur Adressvalidierung. Die Adressvalidierung bietet auch die Möglichkeit, die verfügbaren Landesregionen und Länder abzurufen. Damit kann dem Käufer ein Auswahlfeld angeboten werden, aus dem die zulässigen Optionen ausgewählt werden können. Zusätzlich geben wir in der Länderliste auch an, welche Felder je nach Land erforderlich sind. Damit kann das Formular aktualisiert werden, um die länderabhängigen Felder als erforderlich zu markieren.

Die genannten Felder müssen entweder mit dem Präfix billingAddress oder shippingAddress verwendet werden.

4.2Kundendaten

Sie können einen Parameter customerEmailAddress angeben, der die E-Mail-Adresse des Kunden enthält. Wir senden alle E-Mail-Nachrichten an diese E-Mail-Adresse. Alle weiteren Angaben zum Kunden sollten in der Liefer- oder Rechnungsadresse gemacht werden.

Die customerId kann nicht angegeben werden, da sie für die Verarbeitung von One-Click-Zahlungen verwendet wird; wir ignorieren diesen Anfrageparameter.

4.3Positionen

Wenn Sie die Positionen nicht im Zahlungslink hinterlegen, müssen Sie sie über die Anfrage angeben. Eine Position erfordert mindestens die folgenden Eigenschaften:

  • amountIncludingTax: Der Betrag der Position einschliesslich Steuern.

  • name: Der Name der Position, der in den Dokumenten und E-Mails angezeigt wird.

  • quantity: Die Menge der Position. Der Einzelpreis wird berechnet, indem amountIncludingTax durch quantity geteilt wird.

  • type: Der Typ der Position gibt an, worum es sich bei dem Artikel handelt. Mögliche Typen: PRODUCT, SHIPPING, DISCOUNT oder FEE

  • uniqueId: Die eindeutige ID identifiziert die Position innerhalb einer einzelnen Transaktion.

Die Position kann weitere Eigenschaften haben. Die Positionsmodell-Definition liefert weitere Details zu den anderen Eigenschaften. Nachfolgend finden Sie ein Beispiel für eine Position:

<input type="hidden" name="lineItems[0][uniqueId]" value="t-shirt-123" />
<input type="hidden" name="lineItems[0][sku]" value="t-shirt-red-36" />
<input type="hidden" name="lineItems[0][name]" value="T-Shirt" />
<input type="hidden" name="lineItems[0][amountIncludingTax]" value="40.85" />
<input type="hidden" name="lineItems[0][taxes][0][title]" value="MwSt." />
<input type="hidden" name="lineItems[0][taxes][0][rate]" value="19" />
<input type="hidden" name="lineItems[0][shippingRequired]" value="true" />
<input type="hidden" name="lineItems[0][attributes][color][label]" value="Color" />
<input type="hidden" name="lineItems[0][attributes][color][value]" value="Red" />
<input type="hidden" name="lineItems[0][attributes][size][label]" value="Size" />
<input type="hidden" name="lineItems[0][attributes][size][value]" value="36" />

Wenn Sie mehr als eine Position senden möchten, müssen Sie die Eigenschaften wiederholen und den Index jeweils um eins erhöhen.

Es ist wichtig zu verstehen, dass der Käufer die Positionen verändern kann, wenn sie über die Anfrage angegeben werden. Wir können dies nicht verhindern. Das bedeutet, dass bei jeder Transaktion geprüft werden muss, ob der Betrag nicht vom Käufer verändert wurde.

4.4Währung

Die Währung kann im Parameter currency angegeben werden. Wenn sie bereits im Zahlungslink definiert ist, wird die in der Anfrage gesendete currency ignoriert.

Wenn der Zahlungslink die Positionen definiert und diese nicht in der Anfrage enthalten sind, muss die Währung im Zahlungslink definiert sein.

4.5Fehler- und Erfolgsseite

Wenn die Transaktion autorisiert wurde oder fehlgeschlagen ist, kann der Benutzer auf eine dedizierte Seite weitergeleitet werden. Wenn nichts angegeben wurde, wird der Benutzer auf die Standardseite weitergeleitet.

Der Parameter failedUrl definiert die URL, an die der Benutzer weitergeleitet wird, wenn die Zahlung fehlschlägt. Der Parameter successUrl definiert die URL, an die der Benutzer weitergeleitet wird, wenn die Zahlung erfolgreich autorisiert wurde.

Note
 Sie sollten sicherstellen, dass Sie eine absolute URL und keine relative URL verwenden.

4.6Händlerreferenz

Um eine Händlerreferenz anzugeben, können Sie den Parameter merchantReference verwenden. Die Händlerreferenz wird in der Transaktionsübersicht angezeigt. Sie kann auch verwendet werden, um nach einer bestimmten Transaktion zu suchen.

Es ist wichtig zu verstehen, dass diese merchantReference vom Käufer geändert werden kann; Sie sollten diese Tatsache daher in den Prozessen berücksichtigen, die Sie einrichten.

4.7Zusätzliche Informationen

Wenn Sie weitere Daten zur Transaktion speichern müssen, können Sie dies über das Feld metaData tun. Es erlaubt, weitere Schlüssel-Wert-Paare zu speichern. Wenn Sie beispielsweise im Schlüssel comment einen Kommentar zum Kauf speichern möchten, können Sie dies tun, indem Sie im Parameter metaData[comment] einen Kommentar übergeben. Für die Metadaten gelten einige Limiten. Weitere Details finden Sie im Abschnitt Metadaten der Webservice-API.

4.8Verfügbarkeit nach Datum und Uhrzeit steuern

Die Verfügbarkeit des Zahlungslinks kann mit den Parametern availableFrom und availableUntil gesteuert werden. Diese Parameter werden auf dieselbe Weise interpretiert wie die entsprechenden Optionen am Zahlungslink. Werden sie jedoch über den Zahlungslink bereitgestellt, kann der Käufer sie umgehen. Sollen sie so durchgesetzt werden, dass der Käufer sie nicht manipulieren kann, müssen die entsprechenden Optionen am Zahlungslink selbst verwendet werden.

Die akzeptierten Datumsangaben für availableFrom und availableUntil müssen im Format ISO 8601 vorliegen. Zum Beispiel:

  • 2018-05-01

  • 2018-08-09T10:10:10

  • 2018-08-09T10:10:10+02:00

Enthält das Datum keine Zeitzone, wird die UTC-Zeitzone angenommen. Beachten Sie, dass Sie das Datum gegebenenfalls URL-kodieren müssen.

5Wie gehe ich mit der Validierung um?

Wir validieren die Formulardaten. Allerdings müssen wir den Fehler auf einer dedizierten Seite anzeigen, was für die Benutzererfahrung nicht optimal ist. Wir empfehlen, die Adressvalidierung zu verwenden, um die Adresse im Browser zu validieren, bevor das Formular an die Zahlungslink-URL gesendet wird. Die Adressvalidierung bietet auch die Möglichkeit, die Länder und Landesregionen abzurufen.

Wir validieren die Eingaben serverseitig erneut. So stellen wir sicher, dass keine fehlerhaften Daten verarbeitet werden.

6Kann ich der Zahlungsseite allgemeine Geschäftsbedingungen hinzufügen?

Wir empfehlen, Ihrem Website-Formular eine Bestätigung für allgemeine Geschäftsbedingungen hinzuzufügen. Wenn Sie den Benutzer jedoch zwingen möchten, bestimmte Geschäftsbedingungen zu akzeptieren, können Sie das Zahlungsseiten-Add-on für die allgemeinen Geschäftsbedingungen verwenden, das den Benutzer zwingt, Ihre Bedingungen zu akzeptieren.

7Warum kann ich One-Click-Zahlungen nicht mit Zahlungslinks verwenden?

One-Click-Zahlungen erlauben dem Käufer, die Zahlungsdaten zu speichern. Bei späteren Käufen muss der Käufer die Zahlungsdaten nicht erneut eingeben.

Da wir den Kunden nicht authentifizieren, können wir dem Kunden nicht erlauben, ohne Eingabe von Zahlungsdaten zu bezahlen. Deshalb können Sie die One-Click-Zahlungsfunktion nicht mit Zahlungslinks verwenden. Wenn Sie die One-Click-Zahlungsfunktion für die Zahlart aktivieren, müssen wir sie ignorieren.

Staging 2.218.1