Dokumentation
Dokumentation
Abos

1Abonnements

Nachdem ein Produkt und ein Abonnent erstellt wurden, muss der Abonnent auf ein Abonnement abonniert werden.

1.1Abonnements über das Backend erstellen

Sie können Abonnements direkt über das Backend erstellen. Dazu müssen Sie zu Space > Abonnement navigieren.

iframe
Figure 1. Wählen Sie im Backend einen Abonnenten und ein Produkt aus.

Zuerst müssen Sie den Abonnenten auswählen, den Sie auf ein Produkt abonnieren möchten. Auf der folgenden Seite wird Ihnen ein zusätzlicher Dialog angezeigt, der nach einer Referenz fragt und eine Übersicht über die monatlichen Kosten bietet, die Sie im Produkt definiert haben.

iframe
Figure 2. Konfigurieren Sie das Abonnement für den Abonnenten.
Note
 In diesem Beispiel ist kein Token vorhanden und ausgewählt. Dadurch wird ein Charge Flow ausgelöst, bei dem eine E-Mail an den Abonnenten gesendet wird, in der er nach seinen Zahlungsdaten gefragt wird. Falls Sie diese Zahlungsinformationen bereits in einem gültigen Token gespeichert haben, ist es wichtig, dass Sie den Token hier auswählen. Weitere Informationen zur Token-Erstellung finden Sie in der Tokenisierungsdokumentation.

1.2Web Service API

Ein Abonnement kann auch über die Web-Service-API erstellt werden. Es gibt zwei Möglichkeiten, ein Abonnement zu initialisieren.

1.2.1Übersicht

Wir müssen zwischen zwei verschiedenen Formen unterscheiden, wie Abonnements initialisiert werden können:

  1. Sie integrieren den Abonnementdienst in Ihre Website mit einem Boarding-Prozess, bei dem der Abonnent anwesend ist und Sie seine Zahlungsdaten sofort erfassen möchten. In diesem Fall müssen Sie den Service initializeSubscriberPresent verwenden. Dies erstellt eine confirmed Zahlungstransaktion, die verwendet werden kann, um die Payment-Page-URL oder das JavaScript zu erstellen, wie in der Iframe-Dokumentation beziehungsweise der Payment Page Dokumentation beschrieben.

  2. Sie können auch Charge Flows verwenden, um ein Abonnement zu initialisieren. In diesem Fall verwenden Sie den initialize Service. Mehr über Charge Flows finden Sie in der Charge-Flow-Dokumentation

Sehen Sie sich die folgende Beispielanfrage an, um herauszufinden, wie Sie die Anfragen kombinieren müssen.

1.2.2Token erstellen

Es ist möglich, ein Abonnement mit einem bestimmten Token zu erstellen. Wenn der Token bereits initialisiert und einsatzbereit ist, erfordert die Erstellung des Abonnements keine Eingabe des Abonnenten. Wenn Sie keinen Token angeben, erstellen wir zusammen mit dem Abonnement einen Token. Der neu erstellte Token ist nicht initialisiert. Daher ist es erforderlich, dass der Benutzer die Zahlungsinformationen angibt. Dies kann über die initiale Transaktion des Abonnements erfolgen.

Neben der Erstellung des Tokens durch das System kann er auch manuell erstellt und dem Abonnement zugewiesen werden.

1.2.2.1Token über das Backend erstellen

Tokens können über das Backend unter Space > Zahlung > Tokens erstellt werden. Klicken Sie dort, um einen neuen Token zu erstellen.

1.2.2.2Token über die Web Service API erstellen

Tokens können auch über die Web-Service-API erstellt werden, indem Sie die create Operation auf dem Token Service verwenden.

Anfrage

{
	"enabledForOneClickPayment": true,
	"externalId": "customer-id-1",
	"tokenReference": "customer-id-1"
}
Note
 Die externaId muss eindeutig sein. Wenn Sie die externalID erneut senden, wird der Token aktualisiert.
Note
 Wenn Sie Entitäten aktualisieren, müssen Sie die Versionseigenschaft erhöhen, um die Konsistenz zu wahren.

1.2.3Abonnement erstellen

Ein Abonnement kann auch über die API erstellt werden. Dazu müssen Sie den Subscription Service verwenden.

{
	"currency": "EUR",
	"product": {
		"id": 2
	},
	"selectedComponents": [{
		"id": 4
	}, {
		"id": 2
	}],
	"subscription": {
		"reference": "subscription-subscriber-101",
		"subscriber": {
			"id": 2
		},
		"token": {
			"id": 3
		}
	}
}

Dies erstellt ein Abonnement im Status PENDING mit den angegebenen Produktkomponenten und Eigenschaften. Als nächste Schritte müssen wir das Abonnement mit Initialize initialisieren. Dies kann auf zwei Arten erfolgen.

  1. In der Regel ist der Abonnent in Ihrer Anwendung anwesend und Sie möchten, dass er die Zahlungsdaten direkt im Boarding-Prozess angibt. In diesem Fall verwenden Sie die initializeSubscriberPresent Operation auf dem Subscription Service

  2. Falls Ihr Abonnent nicht anwesend ist, können Sie ihm auch über den Charge Flow einen Zahlungslink senden, über den er gebeten wird, seine Zahlungsinformationen anzugeben. In diesem Fall verwenden Sie die initialize Operation auf dem Subscription Service

1.2.4Ein Abonnement mit anwesendem Abonnenten initialisieren

Sobald das Abonnement erstellt ist, können wir die Transaktion mit der initializeSubscriberPresent Operation auf dem Subscription Service initialisieren.

Anfrage

POST request to the following endpoint:

/api/v2.0/subscriptions/2/initialize-subscriber-present
{
	"successUrl": "http://www.yoursuccessurl.com",
	"failureUrl": "http://www.yourfailedurl.com"
}

Antwort

{
	"createdOn": "2017-04-26T12:08:37.602Z",
	"discardedBy": 0,
	"externalId": "subscription-2",
	"failedUrl": "http://www.yourfailedurl.com",
	"id": 2,
	"ledgerEntries": [],
	"linkedSpaceId": 1,
	"plannedExecutionDate": "2017-04-26T12:08:37.152Z",
	"plannedPurgeDate": "2017-05-12T12:08:37.333Z",
	"processingType": "SYNCHRONOUS",
	"state": "PROCESSING",
	"subscription": {
		"id": 2
	},
	"succeedOn": null,
	"successUrl": "http://www.yoursuccessurl.com",
	"transaction": {
	  "id": 2
	},
	"type": "AUTOMATIC",
	"version": 1
}

Dies erstellt eine Zahlungstransaktion im Status confirmed. Die Transaktions-ID, die in der Antwort zurückgegeben wird, kann nun verwendet werden, um entweder buildJavaScriptUrl oder buildPaymentPageUrl auszuführen und eine IFrame oder Payment Page Autorisierung zu erstellen.

Beispiel

Im Beispiel verwenden wir die GET Anfrage an buildPaymentPageURL, um die URL zu erhalten, zu der Sie Ihren Händler weiterleiten, damit er die Zahlungsinformationen angibt und die Initialisierung des Abonnements abschliesst. Wenn die Transaktion im Status fulfill ist, wechselt das Abonnement in den Status Active. Dadurch wird auch eine aktive Abonnementversion erstellt.

1.2.5Das Abonnement mit einem Charge Flow initialisieren

Sie können ein Abonnement auch mit einem Charge Flow initialisieren. In diesem Fall verwenden Sie die initialize Operation auf dem Subscription Service.

Dies löst automatisch einen Charge Flow aus und fordert die Zahlungsinformationen von Ihrem Abonnenten an, falls Sie keinen Token angegeben haben oder der Token nicht gültig ist.

Note
 Sie haben nun einen Abonnenten, der auf ein Produkt abonniert ist! Im Hintergrund erstellen wir ein Ledger, in dem wir die Belastungen verfolgen, die während einer Periode anfallen. In jeder Periode wird das Ledger abgeglichen und der ausstehende Betrag dem Kunden belastet. Dies erstellt eine Transaktion und eine zugehörige Rechnung. Die Rechnung zeigt auf, was der Kunde schuldet, gibt an, wann er belastet wird oder wurde, und verfolgt den Zahlungsstatus. Sie können über die API oder im Backend zusätzliche Positionen auf diesem Ledger hinzufügen. Weitere Informationen finden Sie im Abschnitt zur Abrechnung.

1.3Abonnements kündigen

Abonnements können mit der terminate Operation im Subscription Service gekündigt werden. Sie haben die Möglichkeit, die Kündigungsfrist einzuhalten oder das Abonnement sofort zu kündigen. Wenn die Kündigungsfrist eingehalten wird, läuft das Abonnement die angegebene Anzahl von Kündigungsperioden auf der Produktversion weiter, bis das Abonnement schliesslich endet. Wenn Sie das Abonnement sofort kündigen, wird das Abonnement gestoppt, die Periodengebühr wird pro rata berechnet und eine Belastung mit dem ausstehenden Betrag wird ausgelöst. Wenn Sie ein Abonnement kündigen, wird das Abonnement in den Status terminating versetzt, in dem die ausstehenden Beträge belastet werden. Sobald die letzte Belastung erfolgreich abgeschlossen ist, versetzen wir das Abonnement in den Status terminated.

Anfrage

spaceId=1&subscriptionId=2&respectTerminationPeriod=true

2Ein Abonnement ändern

In der Regel ändert sich ein Abonnement im Laufe der Zeit. Es gibt mehrere Gründe für eine Änderung. Entweder möchte der Benutzer einen anderen Plan (z.B. Wechsel vom basic plan zum pro plan) oder das Produkt selbst ändert sich. Eine Produktänderung kann erfordern, dass das Abonnement auf die neueste Produktversion aktualisiert wird.

Eine Änderung kann sofort oder gemäss der Kündigungsfrist angewendet werden. Wenn eine sofortige Änderung veranlasst wird, wird die aktuell laufende Periode beendet und die ausstehenden Beträge werden belastet. Periodengebühren werden in diesem Fall pro rata berechnet. Einrichtungsgebühren werden speziell behandelt, siehe Upgrade & Downgrade.

Eine Änderung kann entweder über die API oder über das Backend angewendet werden.

2.1Abonnements im Backend ändern

Abonnements können über das Backend geändert werden, indem die Abonnements bearbeitet werden. Sie können das neue Produkt auswählen und festlegen, ob die Kündigungsfrist berücksichtigt werden soll. Dies führt zur Erstellung einer neuen Abonnementversion für den Abonnenten, die je nach Kündigungseinstellung aktiv wird.

2.1.1Abonnements über die API ändern

Sie können eine Abonnementänderung auch über die Web-Service-API einleiten, indem Sie die applyChanges Operation auf dem Subscription Service verwenden

Die folgende Anfrage aktualisiert mein Abonnement mit der ID 8 auf das neue Pro-Produkt mit der ID 3. Diese Änderungen werden sofort wirksam.

Anfrage

{
	"currency": "CHF",
	"product": {
		"id": 3
	},
	"respectTerminationPeriod": false,
	"selectedComponents": [{
		"id": 14
	}],
	"subscription": {
		"id": 8
	}
}

2.2Downgrade & Upgrade

Einrichtungsgebühren binden den Abonnenten. Die Bindung beim Wechsel zwischen Produkten sollte jedoch reduziert werden. Daher werden die Einrichtungsgebühren beim Wechsel zwischen Produkten in der Regel erstattet. Zum Beispiel muss der Abonnent beim Wechsel vom basic plan zum pro plan die vollen Einrichtungsgebühren des pro plan nicht erneut bezahlen. Es wird ein Rabatt gewährt. Wir nennen diesen Prozess des Wechsels zwischen Produkten mit Einrichtungsgebühren Upgrade bzw. Downgrade. Eine Aktualisierung der Produktversion kann ebenfalls zu einem Upgrade oder Downgrade führen.

Die folgenden Abschnitte sind nur relevant, wenn das Produkt Einrichtungsgebühren hat.

Die folgende Abbildung hilft zu zeigen, wie Downgrades und Upgrades berechnet werden.

iframe
Figure 3. Wie werden Upgrades oder Downgrades berechnet.

Ob Sie ein Upgrade oder ein Downgrade durchführen, wird durch zwei Parameter bestimmt:

  • weight: Das Gewicht kann auf der Produktkomponente gesetzt werden.

  • product-reference: Die Produktreferenz wird ebenfalls auf der Produktkomponente gesetzt.

Falls Sie ein Abonnement ändern, vergleichen wir die Komponenten der alten und der neuen Produktversion.

  1. Zunächst wird dem Abonnenten die Einrichtungsgebühr der neuen Produktversion belastet. In der Abbildung oben sehen Sie, dass die neue Produktversion eine Einrichtungsgebühr von 150 EUR für die Komponente Support Pro hat. Diese wird also unmittelbar nach der Durchführung der Änderung belastet.

  2. Basierend auf dem Gewicht und den Einstellungen der Komponente in der alten Produktversion erfolgt eine Upgrade- oder Downgrade-Gutschrift auf sein Ledger. In der Abbildung oben haben wir auf der Komponente Support festgelegt, dass es im Falle eines Upgrades eine Gutschrift von 50 EUR gibt.

  3. Zunächst prüfen wir, ob die Komponente bereits in der alten Produktversion in derselben Komponentengruppe vorhanden war. Wenn wir die Referenz finden, vergleichen wir die Gewichte, um festzustellen, ob es sich um ein Upgrade oder ein Downgrade handelt.

  4. Da das weight der Komponente Support Pro höher ist, wird die Änderung als Upgrade betrachtet und die 50 EUR werden dem Ledger des Abonnenten gutgeschrieben.

  5. Falls der Komponentengruppe eine neue Komponente hinzugefügt wird, die in der alten Produktversion nicht vorhanden war, erfolgt keine Gutschrift.

Die Änderung der Abonnementversion des Abonnenten führt zu einer Gutschrift, die auf dem Abonnement-Ledger des Abonnenten zu sehen ist.

iframe
Figure 4. Sehen Sie die 50 EUR, die dem Ledger des Abonnenten gutgeschrieben werden.