Dokumentation
Dokumentation
Payment Page

1Einführung

Um eine Zahlung über die Plattform zu erstellen, haben Sie die Wahl zwischen der payment page integration, bei der der Kunde auf unsere Zahlungsseite weitergeleitet wird, der iframe integration, bei der das Zahlungsformular über unsere JavaScript-Integration in einem iframe platziert wird, oder der lightbox integration, um eine nahtlose und PCI-DSS-konforme Integration in Ihrem Checkout zu erreichen.

Der Ablauf der Zahlungsseite ist wie folgt (vereinfacht):

  1. Erstellen Sie ein transaction object über unsere API.

  2. Fragen Sie die URL der Zahlungsseite an.

  3. Leiten Sie den Benutzer auf die Zahlungsseite weiter.

  4. Verarbeiten Sie die eingehende Webhook-Anfrage, um die Transaktion in der Händleranwendung zu autorisieren.

2Systeminteraktionen

Zahlungsseiten-Integration
Figure 1. Sequenzdiagramm der Zahlungsseiten-Integration

3Details zur Integration der Zahlungsseite

Bevor Sie mit der Integration der Zahlungsseite beginnen, sollten Sie:

  1. Ein Konto erstellen und sich registrieren.

  2. Einen Anwendungsbenutzer unter Account > Benutzer > Anwendungsbenutzer erstellen.

  3. Lernen, wie Sie sich bei unserem Webservice authentifizieren und verbinden.

Note
 Werfen Sie bitte einen Blick auf unser GitHub-Repository, in dem wir SDK in verschiedenen Sprachen zum Download anbieten, die Ihren Integrationsaufwand drastisch reduzieren.

Wir bieten Ihnen ausserdem einen API Client, mit dem Sie die an die API gesendeten Anfragen testen und die Antworten einsehen können.

3.1Ablauf

  1. Wenn der Kunde den Checkout abschliesst, erstellen Sie eine Bestellung in Ihrem Shop.

  2. Sie müssen ein transaction object mit der create Methode des Transaction Service erstellen.

  3. Verwenden Sie den build payment page URL Service, um die URL der Zahlungsseite zu erstellen, und leiten Sie den Kunden auf diese URL weiter. Der Kunde gibt die Zahlungsdaten auf der Zahlungsseite ein. Je nach Zahlart wird er bei Bedarf weitergeleitet.

  4. Wenn die Transaktion auf unserer Seite verarbeitet wurde oder fehlgeschlagen ist, wird der Kunde auf die successUrl oder failedUrl weitergeleitet, die beim Erstellen des Transaktionsobjekts definiert wurde.

  5. Warten Sie auf die Benachrichtigung, um die Bestellung im Händlersystem als authorized oder failed zu markieren.

Sie können diesen Ablauf verbessern, indem Sie den Kunden die Zahlart bereits in der Händleranwendung auswählen lassen. Mit der fetch possible payment methods Operation des Transaction Service bieten wir die Möglichkeit, die aktivierten Zahlarten für einen bestimmten Space abzurufen. Da wir hier den Integrationsmodus der Zahlungsseite beschreiben, müssen Sie payment_page als Integrationsmodus übergeben.

Als Ergebnis liefert die Methode die möglichen Zahlarten zurück. Diese Zahlarten bilden die Grundlage der Liste der Zahlarten, die dem Kunden angezeigt werden. Die Eigenschaft allowedPaymentMethods des Transaktionsobjekts erlaubt es, die zulässigen Zahlarten für die jeweilige Transaktion auf die zuvor vom Kunden getroffene Auswahl einzuschränken.

3.1.1Ein Transaktionsobjekt erstellen

Um ein Transaktionsobjekt zu erstellen, müssen Sie die Operation zum Erstellen einer Transaktion verwenden. Hier übergeben Sie die Ihnen vorliegenden Kundendaten einschliesslich der Positionen und Preise. Dadurch wird eine Transaktion im Zustand pending in Ihrem Space erstellt.

Anfrage

{
   "billingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"some-buyer@wallee.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"Neuwiesenstrasse 15"
   },
   "currency":"EUR",
   "language":"de-CH",
   "lineItems":[
	  {
		 "amountIncludingTax":"11.87",
		 "name":"Barbell Pull Up Bar",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"barbell-pullup",
		 "type":"PRODUCT",
		 "uniqueId":"barbell-pullup"
	  },
	  {
		 "amountIncludingTax":"559",
		 "name":"Rowing Machine",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"rowing-machine",
		 "type":"PRODUCT",
		 "uniqueId":"rowing-machine"
	  },
	  {
		 "amountIncludingTax":"17.98",
		 "name":"Super Whey Protein",
		 "quantity":"4",
		 "shippingRequired":"true",
		 "sku":"super-whey",
		 "taxes":[
			{
			   "rate":"10",
			   "title":"VAT"
			},
			{
			   "rate":"3.5",
			   "title":"Supplement Fee"
			}
		 ],
		 "type":"PRODUCT",
		 "uniqueId":"super-whey"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Special Chär Test",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"special-chär-test",
		 "type":"SHIPPING",
		 "uniqueId":"special-chär-test"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Standard Shipping",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"standard-shipping",
		 "type":"SHIPPING",
		 "uniqueId":"standard-shipping"
	  },
	  {
		 "amountIncludingTax":"-10",
		 "name":"Spring Discount",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"spring-discount",
		 "type":"DISCOUNT",
		 "uniqueId":"spring-discount"
	  }
   ],
   "merchantReference":"DEV-2630",
   "shippingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"some-buyer@wallee.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"Neuwiesenstrasse 15"
   }
}

Antwort

Die Antwort, die Sie erhalten, enthält die id (im folgenden Beispiel 109472), die nun verwendet wird, um weitere Operationen mit dieser Transaktion durchzuführen.

{
	"allowedPaymentMethodBrands": [],
	"allowedPaymentMethodConfigurations": [],
	"authorizationAmount": 603.85,
	"authorizationTimeoutOn": "2017-12-07T08:44:09.119Z",
	"autoConfirmationEnabled": true,
	"chargeRetryEnabled": true,
	"confirmedBy": 0,
	"createdBy": 0,
	"createdOn": "2017-12-07T08:14:09.119Z",
	"currency": "EUR",
	"customersPresence": "VIRTUAL_PRESENT",
	"endOfLife": "2017-12-21T08:14:09.119Z",
	"group": {
		"id": 109478
	},
	"id": 109472,
	"language": "de-CH",
	"linkedSpaceId": 396,
	"merchantReference": "DEV-2630",
	"metaData": {},
	"plannedPurgeDate": "2017-12-21T08:14:09.119Z",
	"refundedAmount": 0,
	"state": "PENDING",
	"timeZone": "Z",
	"version": 1
}

3.1.2Transaktionen aktualisieren

Transaktionseigenschaften können aktualisiert werden, solange sich die Transaktion nicht im Zustand confirmed befindet. Verwenden Sie dazu die update Operation des Transaction-Service.

Note
 Werfen Sie einen Blick auf den Abschnitt Objektversionierung / Sperrung, der beschreibt, wie Sie mit der Eigenschaft version umgehen müssen, um Konflikte durch optimistisches Sperren zu vermeiden.

Anfrage

Im folgenden Beispiel aktualisieren wir die Positionen und entfernen die Rabattposition, die wir im obigen Beispiel hinzugefügt haben.

{
	"billingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@wallee.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "Neuwiesenstrasse 15"
	},
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"lineItems": [
		{
			"amountIncludingTax": "11.87",
			"name": "Barbell Pull Up Bar",
			"quantity": "1",
			"sku": "barbell-pullup",
			"type": "PRODUCT",
			"uniqueId": "barbell-pullup"
		},
		{
			"amountIncludingTax": "559",
			"name": "Rowing Machine",
			"quantity": "1",
			"sku": "rowing-machine",
			"type": "PRODUCT",
			"uniqueId": "rowing-machine"
		},
		{
			"amountIncludingTax": "17.98",
			"name": "Super Whey Protein",
			"quantity": "4",
			"sku": "super-whey",
			"type": "PRODUCT",
			"uniqueId": "super-whey"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Special Chär Test",
			"quantity": "1",
			"sku": "special-chär-test",
			"type": "SHIPPING",
			"uniqueId": "special-chär-test"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Standard Shipping",
			"quantity": "1",
			"sku": "standard-shipping",
			"type": "SHIPPING",
			"uniqueId": "standard-shipping"
		}
	],
	"merchantReference": "DEV-2630",
	"shippingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@wallee.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "Neuwiesenstrasse 15"
	},
	"version": 3
}

Antwort

Die Antwort enthält das aktualisierte Transaktionsobjekt.

{
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"merchantReference": "DEV-2630",
	"version": 3
}

3.1.3Zahlungsvorauswahl umsetzen

Für eine bessere Integration ist es hilfreich, wenn Sie Ihren Kunden bereits im Checkout anzeigen, welche Zahlarten auf Basis der Daten im Transaktionsobjekt verfügbar wären. Die Antwort sollte gerendert und als Zahlungsoptionen in Ihrem Checkout angezeigt werden.

Um die Zahlart auf der Transaktion vorauszuwählen, sollten Sie die Transaktion wie zuvor gezeigt aktualisieren, indem Sie die allowedPaymentMethodConfiguration ID übergeben, die von fetchPossiblePaymentMethods für die jeweilige Transaktion zurückgegeben wird.

Antwort

Die Antwort liefert die möglichen Zahlarten für die jeweilige Transaktion zurück.

{
	"data": [{
		"dataCollectionType": "ONSITE",
		"description": {
			"en-US": ""
		},
		"id": 510,
		"imageResourcePath": null,
		"linkedSpaceId": 396,
		"name": "Credit / Debit Card",
		"oneClickPaymentMode": "ALLOW",
		"paymentMethod": {
			"id": 1457546097597
		},
		"plannedPurgeDate": null,
		"resolvedDescription": {
			"en-US": "Pay conveniently with your credit or debit card."
		},
		"resolvedImageUrl": "https://staging-wallee.com/s/396/resource/icon/payment/method/credit-debit-card.svg",
		"resolvedTitle": {
			"en-US": "Credit / Debit Card"
		},
		"sortOrder": 1,
		"spaceId": 396,
		"state": "ACTIVE",
		"title": {
			"en-US": ""
		},
		"version": 2
	}],
	"hasMore": false,
	"limit": 1
}

Nun können Sie diese Informationen verwenden, um die Zahlartenauswahl in Ihrem Shop darzustellen. Sobald der Kunde die Zahlart gewählt hat, können Sie die obige Transaktion aktualisieren, indem Sie die allowedPaymentMethodConfigurations mit der update Operation des Transaction-Service übergeben.

Anfrage

{
	"allowedPaymentMethodConfigurations": [
		{
			"id": 507
		}
	],
	"id": 109472,
	"version": 4
}

3.1.4URL der Zahlungsseite erstellen

Um den Kunden auf die Zahlungsseite weiterzuleiten, verwenden Sie die URL der Zahlungsseite erstellen Operation, die die URL der Zahlungsseite zurückliefert, auf die der Kunde weitergeleitet werden soll.

Note
 Wir bieten viel Flexibilität, um das Erscheinungsbild der Zahlungsseite mit unserem Ressourceneditor zu gestalten. Weitere Informationen finden Sie in der Dokumentation zu Ressourcen und Anpassung.

3.1.5Transaktionsaktualisierungen abrufen

Um über den Transaktionsstatus informiert zu bleiben, sollten Sie auf Ihrer Seite Webhook-Benachrichtigungen registrieren. Die Webhooks informieren Sie über Statusänderungen der ausgewählten Entitäten und sollten Ihre Anwendung veranlassen, die Transaktionsergebnisse weiterzuverarbeiten.

Weitere Informationen zu Webhooks, Webhook-Listenern und deren Konfiguration finden Sie in der Webhooks-Dokumentation.

Staging 2.218.1