Payments / Features / OAuth

Using OAuth 2.0 to Access Novalnet APIs

Novalnet APIs use the OAuth 2.0 protocol for authentication and authorization. To begin, obtain OAuth 2.0 Payment access key from the Novalnet Admin Portal.

Then your application requests an access token from the Novalnet Authorization Server, extracts a token from the response, and sends the token to the Novalnet API you want to access.

Basic steps

All applications take a basic approach when accessing the Novalnet API using OAuth 2.0.

Step 1 : Obtain payment access key from the Novalnet Admin Portal.

To authenticate your payment requests, use Novalnet's custom header authentication. The custom header field is constructed as follows:

Each header request is built using the Payment access key. To get your Payment Access Key, login to your Novalnet Admin Portal and navigate to the path Projects -> [Select Desired Project] -> API credentials -> Payment access key.
The Payment Access Key should be encoded using a variant of Base64.
The resultant base64_encoded value should be passed in the Novalnet's custom header key X-NN-Access-Key.
The custom header field is formulated in the format
X-NN-Access-Key:base64_encoded_value.

All payment requests must be carried out through an HTTPS connection along with the header values, otherwise, the request will fail with authorization error messages.

Your Payment Access Key carry many privileges, so be sure to keep them secure! Do not share your secret Payment Access Key in publicly accessible areas such as GitHub, client-side code, and so forth.

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, 
	];
?>

Step 2 : Request an access token from the Novalnet Authorization Server.

For accessing the Novalnet API your application must obtain an access token. This access token has authority to grant access to multiple APIs but only for a specific period of time. This period can be set using expires_in param.

A variable parameter called type controls the set of resources and operations that an access token permits.

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'       => 'EN',  
	];
	$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;
	}
?>

Step 3 : Submit the access token parameters to Novalnet API.

After obtaining the access token, it sends the token to a Novalnet API in an HTTP Authorization request header.

These tokens are valid only for the set of operations and resources in the access object of the token request. For instance, if an access token is issued for the payment.write, it does not grant access to the other Novalnet API.

Authorization scopes

Access to Novalnet API is divided into scopes which grant access to different API endpoints.For each access token, a subset of scopes can be requested. This way, you can selectively request the right set of information depending on the use case.

Action	Scope	Description
payment	payment.write	Books the amount immediately after authorizing and capturing all at once or authorizes to book the amount. In case of Seamless payment form, it processes real-time payments directly to your website.
transaction_capture	transaction.write	This access to collects the funds due from the completed authorizations.
transaction_cancel	transaction.void	This scope is used to avoid collecting the funds from previously completed authorizations.
transaction_refund	transaction.write	This scope returns funds that were already collected by a Payment or a Capture transaction.
transaction_update	transaction.write	To synchronize a transaction from Novalnet for an order in the shop admin panel, create an order, choose a customer, enter the transaction ID generated at Novalnet and click Create to update the transaction details.
transaction_details	transaction.read	This will access you to retrieve the result of a transaction sent previously using Novalnet's TID.
subscription_update	subscription.write	This will access you to update the existing subscription's attributes like amount or next recurring date.
subscription_suspend	subscription.write	This scope will pause the existing subscription.
subscription_reactivate	subscription.write	This scope will reactivate the existing subscription which has been suspended before.
subscription_cancel	subscription.void	This scope will cancel the existing subscription.
merchant_details	merchant.read	This scope will return the enabled payment method in Novalnet along with the particular merchant details.
instalment_cancel	instalment.write	This scope will cancel the existing instalment.
transaction_invoice	invoicing.create	This action is used to create the Customer Invoice pdf generation.
webhook_configure	webhook.write	This scope is used to configure webhook URL for notification handling.
affiliate_create	affiliate.create	As the name suggests, this action will create the affiliate vendor for the corresponding owner.