Verwendung von OAuth 2.0 um auf Novalnet-APIs zuzugreifen

Die Novalnet-APIs verwenden das OAuth 2.0-Protokoll zur Authentifizierung und Autorisierung. Um anzufangen, beschaffen Sie sich den OAuth 2.0 Paymentzugriffsschlüssel aus dem Novalnet Admin-Portal.

Dann schickt Ihre Anwendung eine Anfrage zu einem Zugriffstoken an den Novalnet-Autorisierungsserver, extrahiert das Token aus der Rückmeldung und schickt es an die Novalnet-API, auf welche Sie zugreifen wollen.

Grundlegende Schritte

Alle Anwendungen folgen einem grundlegenden Ansatz, wenn sie auf die Novalnet-API unter Einsatz von OAuth 2.0 zugreifen.

Schritt 1: Beschaffen Sie sich den Paymentzugriffsschlüssel aus dem Admin-Portal.

Um Ihre Zahlungsaufrufe zu authentifizieren, setzen Sie die Authentifizierung der benutzerdefinierten Header durch Novalnet ein. Das benutzerdefinierte Headerfeld ist wie folgt aufgebaut:

Jeder Header eines Aufrufs wird unter Verwendung des Paymentzugriffsschlüssels key erstellt. Um Ihren Paymentzugriffsschlüssel zu erhalten, loggen Sie sich in Ihr Novalnet Admin-Portal und folgen Sie dem Pfad Projekte -> [Wählen Sie Ihr gewünschtes Projekt aus] -> API-Anmeldeinformationen -> Paymentzugriffsschlüssel
Der Paymentzugriffsschlüssel sollte mit einer Variante von Base64 codiert werden.
Der resultierende, mit Base64 codierte Wert, sollte in dem benutzerdefinierten Header in dem Feld X-NN-Access-Key an Novalnet übergeben werden.
Das benutzerdefinierte Header-Feld ist in dem Format
X-NN-Access-Key:base64_encoded_value spezifiziert.

Alle Zahlungsanfragen müssen über eine HTTPS-Verbindung zusammen mit den Werten im Header ausgeführt werden, sonst schlägt der Aufruf mit einer Fehlermeldung zur Autorisierung fehl.

Ihr Paymentzugriffsschlüssel ist mit vielen Berechtigungen verbunden, stellen Sie deshalb sicher, dass Sie ihn sicher aufbewahre! Teilen Sie Ihren geheimen Paymentzugriffsschlüssel nicht in öffentlich zugänglichen Bereichen mit wie GitHub, Code auf Kundenseite usw.

PHP

<?php
	// Need to enter your payment access key value here
	$payment_access_key = '###YOUR_PAYMENT_ACCESS_KEY###';

	// Now, have to encode the $payment_access_key value with the base64 encode
	$encoded_data       = base64_encode($payment_access_key);

	// Build the Headers array
	$oauth_header = [
	
		// The Content-Type should be "application/json"
		'Content-Type:application/json', 
		
		// The charset should be "utf-8"
		'Charset:utf-8', 
		
		// Optional
		'Accept:application/json', 
		
		// The formed authenticate value (case-sensitive)
		'X-NN-Access-Key:' . $encoded_data, 
	];
?>

Schritt 2: Schicken Sie einen Aufruf an den Novalnet-Autorisierungsserver, um ein Zugriffstoken zu erhalten.

Um auf die Novalnet-API zuzugreifen, muss Ihre Anwendung ein Zugriffstoken erhalten. Dieses Zugriffstoken hat die Möglichkeit, Zugang zu mehreren APIs zu verschaffen, jedoch nur für einen bestimmten Zeitraum. Dieser Zeitraum kann gesetzt werden, indem Sie den Parameter expires_in verwenden.

Ein variabler Parameter namens type kontrolliert die Menge der Ressourcen und Handlungen, welche ein Zugriffstoken ermöglicht.

PHP

<?php
	// Need to enter your payment access key value here
	$payment_access_key  = '###YOUR_PAYMENT_ACCESS_KEY###';

	// Action Endpoint 
	$oauth_endpoint   = 'https://payport.novalnet.de/v2/oauth/token';

	// Now, have to encode the $payment_access_key value with the base64 encode
	$encoded_data       = base64_encode($payment_access_key);

	// Build the Headers array
	$oauth_header = [

		// The Content-Type should be "application/json"
		'Content-Type:application/json', 
		
		// The charset should be "utf-8"
		'Charset:utf-8', 
		
		// Optional
		'Accept:application/json', 
		
		// The formed authenticate value (case-sensitive)
		'X-NN-Access-Key:' . $encoded_data, 
	];

	// Build oauth access request
	$oauth_data['access'] = [

		// the type of transaction need to perform
		'type'       => 'payment.write', 
		'expires_in' => '300', 
	];
	$oauth_data['custom'] = [

		// Shopper's selected language in shop
		'lang'       => 'DE',  
	];
	$response = send_request($oauth_data, $oauth_endpoint, $oauth_header, 'OAUTH');
	
	function send_request($data, $url, $headers) {
		
		// Initiate cURL
		$curl = curl_init();
		
		// Set the url
		curl_setopt($curl, CURLOPT_URL, $url);
		
		// Set the result output to be a string
		curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
		
		// Set the POST value to true (mandatory)
		curl_setopt($curl, CURLOPT_POST, true);
		
		// Set the post fields
		curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
		
		// Set the headers
		curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

		// Execute cURL
		$result = curl_exec($curl);

		// Handle cURL error
		if (curl_errno($curl)) {
			echo 'Request Error:' . curl_error($curl);
			return $result;
		}
		
		// Close cURL
		curl_close($curl);  
		
		// Decode the JSON string
		$result = json_decode($result, true);
		
		return $result;
	}
?>

Schritt 3: Übergeben Sie die Parameter zum Zugriffstoken an die Novalnet-API

Nachdem Sie das Zugriffstoken erhalten haben, schicken Sie das Token im Header eines HTTP-Autorisierungsaufrufs an die Novalnet-API.

Diese Token sind nur für die Menge an Handlungen und Ressourcen im access-Objekt des Token-Aufrufs gültig. Zum Beispiel verschafft ein für payment.write ausgegebenes Zugriffstoken keinen Zugriff auf andere Novalnet-APIs.

Bereich der Autorisierung

Der Zugriff auf die Novalnet-API ist in Bereiche aufgeteilt, mit denen der Zugriff auf verschiedene API-Endpunkte verbunden ist. Für jedes Zugriffstoken kann eine Untermenge von Bereichen verlangt werden. Auf diese Weise können Sie punktuell die richtige Menge an Informationen aufrufen abhängig vom Anwendungsfall.

Funktion	Bereich	Beschreibung
payment	payment.write	Bucht den Betrag Sofortüberweisung, nachdem Autorisierung und Einzug alle gleichzeitig durchgeführt wurden oder führt eine Autorisierung durch, damit der Betrag abgebucht werden kann. Im Falle eines nahtlosen Zahlungsformulars werden Zahlungen in Echtzeit direkt an Ihre Website übermittelt.
transaction_capture	transaction.write	Dieser Zugang dient zum Einziehen von Guthaben aus abgeschlossenen Autorisierungen.
transaction_cancel	transaction.void	Dieser Zugang wird verwendet, um den Einzug für vorher abgeschlossene Autorisierungen zu verhindern.
transaction_refund	transaction.write	Dieser Zugang gibt Guthaben zurück, welche schon durch eine Zahlung oder einen Einzug eingetrieben wurden.
transaction_update	transaction.write	Um eine Transaktion bei Novalnet mit einer Bestellung im Shop-Admin-Panel zu synchronisieren, legen Sie eine Bestellung an, wählen Sie einen Kunden aus, geben Sie die bei Novalnet generierte Transaktions-ID ein und klicken Sie auf Erstellen, um die Transaktionsdaten zu aktualisieren.
transaction_details	transaction.read	Dieser Zugang ermöglicht Ihnen, das Ergebnis einer vorher übermittelten Transaktion einzuholen, indem Sie die TID von Novalnet verwenden.
Abonnement aktualisieren	subscription.write	Dieser Zugang ermöglicht es Ihnen, die Eigenschaften eines existierenden Abonnements zu aktualisieren, wie den Betrag oder das nächste Verlängerungsdatum.
subscription_suspend	subscription.write	Dieser Zugang dient dazu, ein existierendes Abonnement auszusetzen.
Abonnement reaktivieren	subscription.write	Dieser Zugang dient dazu, ein existierendes Abonnement zu reaktivieren, welches vorher ausgesetzt wurde.
Abonnement stornieren	subscription.void	Dieser Zugang dient zum Stornieren eines existierenden Abonnements.
merchant_details	merchant.read	Dieser Zugang gibt die bei Novalnet aktivierten Zahlungsarten zurück, zusammen mit den jeweiligen Händlerdaten.
instalment_cancel	instalment.write	Dieser Zugang dient dazu, ein existierendes Abonnement zu stornieren.
transaction_invoice	invoicing.create	Dieser Zugang dient dazu, eine Rechnung für den Kunden als PDF-Datei zu generieren.
webhook_configure	webhook.write	Dieser Zugang dient dazu, eine URL als Webhook für die Verarbeitung von Benachrichtigungen einzurichten.
affiliate.create	affiliate.create	Wie der Name andeutet, dient dieser Zugang dazu, einen Affiliate (Unterhändler) für den jeweiligen Besitzer /anzulegen.