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.

API-Schlüssel und API-Geheimnis konfigurieren

Zum Konfigurieren des Paars API-Schlüssel/Geheimnis im Merchant Portal gehen Sie wie folgt vor:

1. Melden Sie sich im Merchant Portal an. Gehen Sie zu Developer > Payment API
2. Wenn Sie noch nichts konfiguriert haben, zeigt der Bildschirm „No keys generated“. Um ein Paar aus API-Schlüssel / Geheimnis zu erstellen, klicken Sie auf „Add API Key“. Der Bildschirm zeigt nun beide Codes in der Tabelle in der Zeile „API Key ID“ / „Secret API Key“ an
   
   

API-Schlüssel und API-Geheimnis konfigurieren

Zum Konfigurieren des Paars API-Schlüssel/Geheimnis im Merchant Portal gehen Sie wie folgt vor:

1. Melden Sie sich im Merchant Portal an. Gehen Sie zu Developer > Payment API
2. Wenn Sie noch nichts konfiguriert haben, zeigt der Bildschirm „No keys generated“. Um ein Paar aus API-Schlüssel / Geheimnis zu erstellen, klicken Sie auf „Add API Key“. Der Bildschirm zeigt nun beide Codes in der Tabelle in der Zeile „API Key ID“ / „Secret API Key“ an
   
   

Den API-Schlüssel und die folgenden Informationen über das Paar ausAPI-Schlüssel und Geheimnis können Sie jederzeit abrufen über Developer > Payment API:

Wenn Sie ein neues Paar aus API-Schlüssel und Geheimnis als Ersatz für ein bestehendes verwenden möchten, gehen Sie wie folgt vor:

1. Klicken Sie auf „Add API Key“. Klicken Sie im Dialogfeld auf „Confirm“, um mit der Erstellung eines neuen Paares aus API-Schlüssel und Geheimnis fortzufahren
   
   

1. Der Bildschirm zeigt nun das neue Paar aus API-Schlüssel und Geheimnis unten in der Tabelle mit dem Status „Active“. Das zuvor aktive Paar hat jetzt den Status „Expiring in xh yym“

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 PAYONE E-Payment 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