Authentifizierung

Erste Schritte

Sicherheit liegt uns am Herzen, deshalb machen wir Ihnen das Abwickeln von Transaktionen wirklich einfach. Damit niemand außer Ihnen Ihre Integration nutzen kann, nutzt unsere Plattform Sicherheitscodes, die mit Ihre PSPID verknüpft sind.

Der so genannte API Key und das API Secret stellen eine eindeutige Signatur für den Datenverkehr zwischen Ihrem System und unserer Plattform dar. Sie können diese für jede Ihrer PSPIDs im Merchant Portal definieren. Jede Anfrage zwischen Servern von Ihrem System an unsere Plattform (über Ihre PSPID) muss sowohl den API Key als auch das API Secret enthalten. Unsere Plattform versucht, die Codes, die wir von Ihnen erhalten, mit denen abzugleichen, die in Ihrer PSPID konfiguriert sind.

Unsere SDKs bieten eine einfache Lösung für diesen Mechanismus, die nur wenige Zeilen Programmierung erfordert. Wenn Sie Ihre eigene Software verwenden möchten, ist auch eine manuelle Implementierung möglich.

Lesen Sie weiter, um zu erfahren, wie das funktioniert und was Sie tun müssen.

Aktuellste API Basis-URL nutzen

2. API Key und API Secret konfigurieren

Gehen Sie wie folgt vor, um Ihren API Key und API Secret in Ihrer PSPID zu konfigurieren:

1. Melden Sie sich im Back Office an. Gehen Sie zu Konfiguration > Technische Informationen > API Einstellungen > Direct API Key
2. Wenn Sie noch nichts konfiguriert haben, zeigt der Bildschirm “No api credential found”. Um sowohl API Key als auch API Secret zu erstellen, klicken Sie auf "ERSTELLEN"
   

1. 
   Das Bild zeigt die Back Office-Nachricht "No api credential found"
   
   
2. Der Bildschirm zeigt nun in der Tabelle in der jeweiligen Spalte "Key" / "Secret" beide Codes an
   

Führen Sie die folgenden Schritte aus, wenn Sie einen neuen API Key und API Secret erstellen möchten

1. Wählen Sie im Dropdownmenü "gültig lassen für X Stunde(n)" einen Zeitraum . Klicken Sie auf die Schaltfläche “ERNEUERN”. Das derzeit verwendete API Key/Secret-Paar läuft nach dem in "Haltbarkeitsdatum" definierten Datum ab
2. Gleichzeitig wird in der ersten Zeile der Tabelle ein neues API Key/Secret-Paar angezeigt. Stellen Sie sicher, dass Sie das API Secret in Ihrem System speichern, da es im Back Office nicht mehr sichtbar ist, wenn Sie dieses Menü erneut aufrufen
3. Um das außer Kraft tretende API Key/Secret-Paar sofort ablaufen zu lassen, klicken Sie auf "VERFALLEN". Unsere Plattform entfernt das jeweilige API Key/Secret -Paar aus der Tabelle und unserer Plattform, wodurch sie für Anfragen unbrauchbar wird.

API Key und API Secret mit SDKs verwenden

Sobald Sie Ihr API Key/Secret-Paar im Merchant Portal eingerichtet haben, können Sie diese für Ihre Anfragen verwenden, die Sie an unsere Plattform richten. Unsere SDKs machen es Ihnen dies wirklich einfach.

Sehen Sie sich dieses Codebeispiel an, das zeigt, wie man sie in eine standardmäßige Hosted Checkout Page Anfrage verwendet::

Authentisierung ohne SDKs

Sie können unsere API ohne SDKs verwenden, indem Sie Anfragen direkt an unsere Endpunkte senden. Dazu müssen Sie einen anderen Authentisierungsmechanismus verwenden.

Sie müssen

• Mit ihrem API Secret über mehrerer HTTP-Headers (die signature contents oder signed-data) hashen, die Sie zusammen mit Ihrer Anfrage senden
• Diesen Hash (die signature) zusammen mit Ihrem API Key versenden, um die Authentisierung zu verfizieren

Schauen Sie sich die folgenden Kapitel an, um zu verstehen, wie dies funktioniert, sowie unsere Beispiele für GET, POST und DELETE.

Grundlagen des Authentisierungsprozesses

Eine GET/POST/DELETE-Anfrage nach diesem Ansatz umfasst die folgenden Schritte:

1. Erstellen eines String-to-Hash, bestehend aus mehreren HTTP-Headern
2. Berechnen des Hashs mithilfe des HMAC-SHA256-Algorithmus und Ihrem API Secret
3. Senden der eigentlichen Anfrage einschließlich Header, Hash und Ihres API Key an unsere Plattform

1. String-to-hash erstellen

Erstellen Sie den String-to-Hash (die signature contents oder signed-data) nach den folgenden Regeln:

• Reihenfolge der Header:
  

  
  <HTTP method>
  <Content-Type>
  <Date>
  <CanonicalizedHeaders>
  <CanonicalizedResource>
  

• Zusammensetzung der individuellen Header und deren Inhalt:
  

  
  <lowercased header name>:<header value>
  

  
  Folgen Sie diese Richtlinien für den Inhalt der folgenden Header:
  
  

  <HTTP method>

  : "GET"/"POST"/"DELETE" (immer in Großbuchstaben)
  

  <Content-Type>

  : Fester Wert "application/json; charset=utf-8" für POST-Anfragen, ein leerer String für GET/DELETE)
  

  <Date>

  : Standard-Header im RFC1123-Format
  

  <CanonicalizedHeaders>

  : Benutzerdefinierte Headers speziell für Direct like X-GCS-ClientMetaInfo
  

  <CanonicalizedResource>

  : Der Ziel-URI ohne HTTP-Methode und einschließlich aller dekodierten Abfrageparameter
  
  
• Wenn ein Header-Wert über mehrere Zeilen umbrochen wird, ist jede Zeile wie hier beschrieben umzuformatieren. Umformatieren Sie den Header, indem Sie eine neue Zeile oder mehrere Leerstellen durch ein einzelnes Leerzeichen ersetzen:
  
  Schauen Sie sich dieses Beispiel an:
  
  Aus
  

  
  A very long line<CR><LF>
  <SPACE><SPACE><SPACE><SPACE>that does not fit on a single line
  

  
  wird
  

  
  A very long line that does not fit on a single line
  
  

• Alle Leerzeichen am Anfang und Ende des Wertes entfernen
  
  

  Schauen Sie sich dieses Beispiel an:
  
  Aus
  
  

  
  <space><space><space>Some text<space><space><space>
  

  wird
  
  

  Some text
  

• Jedes
  
  

   <item> 

  
  wird gefolgt von einer neuen Zeile (Zeilenvorschub), einschließlich des letzten Eintrags

Schauen Sie sich dieses Codebeispiel für eine CreateHostedCheckout-Anfrage an:

Have a look at this code sample for a CreateHostedCheckout request:

2. Den Hash berechnen

Nach dem Erstellen des String-to-Hash (die signature contents oder signed-data) müssen Sie den Hash mit dem MAC-Algorithmus HMAC-SHA256 zusammen mit Ihrem API Secret berechnen.
Das Ergebnis des Hashings ist die signature, die Sie im Authentisierungs-Header Ihrer Anfrage mitsenden müssen.

Schauen Sie sich dieses Codebeispiel an:

3. Die Anfrage versenden

Schließlich können Sie Ihre Anfrage senden, einschließlich

• Header, die Sie für die Erstellung der String-to-Hash-Datei verwendet haben (die signature contents oder signed-data)
• Das in Base64 kodierte Hash-Ergebnis (die „Signatur“) und Ihr API Key (den unsere Plattform zum Identifizieren Ihrer PSPID in unserem Konto nutzt) im HTTP- Header 'Authorization' nach dieser Formel:
  
  

  Authorization = "GCS v1HMAC:" + API Key + ":" + signature

• Der JSON-kodierte Anfragetext für POST-Anfragen (GET/DELETE benötigen keinen Anfragetext)
  Schauen Sie sich dieses Codebeispiel an:

String-to-Hash-Beispiele verstehen

Da die allgemeinen Anforderungen für eine GET/POST/DELETE-Anfrage unterschiedlich sind, gilt dies auch für die Konstruktion des String-to-Hash.
Schauen Sie sich die folgenden Beispiele an, um zu erfahren, wie Sie diese in Ihrem System implementieren können:

1. POST-Anfrage

Der String-to-Hash (die signature contents oder signed-data) für eine CreateHostedCheckout-Anfrage:

POST
application/json; charset=utf-8
Wed, 02 Mar 2022 11:15:51 GMT
/v2/yourPSPID/hostedcheckouts

2. GET-Anfrage

Der String-to-Hash (die signature contents oder signed-data) für eine GetHostedCheckout-Anfrage:

GET

Wed, 02 Mar 2022 11:15:51 GMT
/v2/yourPSPID/hostedcheckouts/yourHostedCheckoutID

3. DELETE request

Der String-to-Hash (die signature contents oder signed-data) für eine DeleteToken-Anfrage:

DELETE

Wed, 02 Mar 2022 11:15:51 GMT
/v2/yourPSPID/tokens/yourTokenID