Encryption (Direct API)

Integration Options Direct API Parameter Reference Encryption

Encryption (Direct API) | Novalnet Docs

This section explains how you could initiate and handle the API call in Novalnet with encrypted parameters in request and response.

If your server has PCI-DSS compliant for credit card payments, you can directly send the card data (it must be in an encrypted format).

If the card is in the PSD2 region, you will receive the redirect URL(result.redirect_url) in response to authenticate the user. Also, you need to send the return URL (transaction.return_url) of your webshop here to redirect back the end-user to your webshop.

Integration Steps

Follow the below steps to perform the encryption process in your webshop,

Step 1: Generating an Unique Key

We need a unique key (A non-NULL Initialization Vector) to carry out the encryption & decryption techniques. It has to be created by you and included in the request header as the custom header (X-NN-Unique-Key).

<?php
/**
 * Get unique id
 *
 * @return string
 */
function get_uniqueid()
{
    return substr(rand(10000000, 99999999).rand(10000000, 99999999), 0, 16);
}
?>

Step 2: Header Setup

In the request header, you have to send the generated unique key in the X-NN-Unique-Key, and also, it should be a base64 encoded.

Before base64 encode the unique key, please store the unique key in your system, which will help to decrypt your response parameter(s). Since all the parameters in the response will be encrypted using the same unique key.

<?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);
	
	// Get unique id
	$unique_id 			= get_uniqueid();

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

	// Build the Headers array
	$headers = [
	
		// 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, 
		
		// The formed unique ID value (case-sensitive)
		'X-NN-Unique-Key:' . $encoded_unique_id
	];
?>

RESULT

HEADERS
[
    "Content-Type:application/json",
    "Charset:utf-8",
    "Accept:application/json",
    "X-NN-Access-Key:MTljYTE0ZTdlYTYzMjhhNDJlMGViMTNkNTg1ZTRjMjI=",
    "X-NN-Unique-Key:OCwgNywgNiwgNSwgNCwgMw=="
]

Step 3: Encrypting sensitive parameters

You can encrypt the sensitive data or all the request parameters before processing the transaction with Novalnet. The Payment access key and the generated unique key (from Step 1) are needed here to encrypt the parameters. However, irrespective of the encrypted parameters, Novalnet encrypts the entire payment response.

We highly recommend encrypting sensitive parameters like transaction.amount, transaction.test_mode, transaction.currency and transaction.payment_data parameters like card_number, card_cvc etc.,

<?php
/**
 * Encryption process
 * 
 * @param $data
 * @param $uniqid
 * @param $payment_access_key
 *
 * @return string
 */
function encrypt_data($data, $uniqid)
{
  // Encryption process
    return htmlentities(base64_encode(openssl_encrypt($data, "aes-256-cbc", '###YOUR_PAYMENT_ACCESS_KEY###', true, $uniqid)));
}

?>

Step 4: Submit the parameters to Novalnet

After handling the encryption technique, need to post the necessary parameters to Novalnet.

Each payment request is separated into so-called objects, which indicate an entity like Merchant, Customer, Transaction, etc. Use the objects which are relevant to your business model/payment type.

To know more about Direct API parameters, refer this >>link<<

<?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);

// Get unique key
$unique_key 	    = generate_unique_key();

$_SESSION['nn_unique_key'] = $unique_key;

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

// Action Endpoint 
$endpoint  			= 'https://payport.novalnet.de/v2/payment';

// Build the Headers array
$headers = [

	// 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,
    
    // The formed unique ID value (case-sensitive)
    'X-NN-Unique-Key:' . $encoded_unique_key
];

$data = [];

// Build Merchant Data
$data['merchant'] = [

	// Your API signature value
    'signature' => '###YOUR_API_SIGNATURE###', 
    
    // Your corresponding tariff ID
    'tariff'    => '###YOUR_TARIFF_ID###',
];

// Build Customer Data
$data['customer'] = [

	// Shopper's gender
    'gender'      => 'u',

	// Shopper's first name
    'first_name'  => 'Max',
    
     // Shopper's last name
    'last_name'   => 'Mustermann', 
    
    // Shopper's email
    'email'       => 'test@novalnet.de', 
    
    // Shopper's billing address
    'billing'     => [
		
		// Name of the company
        'company'      => 'ABC GmbH',
        
        // House number
		'house_no'     => '2',
        
		// Street
		'street'       => 'Musterstr',

		// City
		'city'         => 'Musterhausen',
		
		// zip
		'zip'          => '12345',
		
		// Country's ISO code
		'country_code' => 'DE'
    ],

     // Shopper's Ip address
    'customer_ip' => '###CUSTOMER_IP###',
    
    // Shopper's customer number from the shop
    'customer_no' => '###CUSTOMER_NUMBER###',
    
    // Shopper's birthdate value YYYY-MM-DD 
    'birth_date'  => '1992-06-10', 
    
    // Shopper's Telephone number
    'tel'         => '+49 089 123456',
    
    // Shopper's Mobile number
    'mobile'      => '+49 174 7781423',
    
    // Shopper's fax number
    'fax'         => '+49 89 654321', 
    
    // Shopper's shipping address (optional)
    'shipping' => [
         
        // Pass this parameter if the billing and the shipping address are identical 
		'same_as_billing' => '1',
    
        // First name
        'first_name'    => 'Norbert',
        
        // Last name
        'last_name'     => 'Maier',
        
        // Email
        'email'         => 'test@novalnet.de',
        
        // Name of the company
        'company'       => 'A.B.C. Gerï¿½stbau GmbH',
        
        // House number
		'house_no'      => '9',
    
        // Street
		'street'        => 'Hauptstr',
    
		// City
		'city'          => 'Kaiserslautern',
		
		// zip
		'zip'           => '66862',
		
		// Country's ISO code
		'country_code'  => 'DE',
        
        // Telephone number
        'tel'           => '+49 089 123456',
        
        // Mobile number
        'mobile'        => '+49 174 7781423',
        
		// State
        'state'      => 'Berlin'
    ],

    // Shopper's company vat ID value (optional)
    'vat_id'      => 'DE123456', 
    
    // Shopper's company tax ID value (optional)
    'tax_id'      => '123/123/123',

    // Shopper's company regestration number (optional)
    'reg_no'      => 'HRB1234', 
    
    // Shopper's session value
    'session'     => 'fedgrgst5653653hdgfsvgdsf622627e',
    
    // Use of minimal customer data
    'no_nc'        => '1'
    
];

// Build Transaction Data
$data['transaction'] = [

    // The mode of the transaction
    'test_mode'        => encrypt_data('###TEST_MODE###', $unique_key),
    
	// The Payment type of the transaction
    'payment_type'     => '###PAYMENT_TYPE###',
    
    // The transaction Amount in smaller currency unit
    'amount'           => encrypt_data('###TRANSACTION_AMOUNT###', $unique_key),
    
    // The transaction currency's ISO code
    'currency'         => encrypt_data('###TRANSACTION_CURRENCY###', $unique_key),
    
    // Need to be specify this for the Redirect payment types to which you need to redirect on SUCCESS
    'return_url'       => '###YOUR_RETURN_URL###',
    
    // Need to be specify this for the Redirect payment types to which you need to redirect on FAILURE (optional)
    'error_return_url' => '###YOUR_ERROR_RETURN_URL###',
    
    // The order number of the transaction
    'order_no'         => '###TRANSACTION_ORDER_NUMBER###',
    
    // The Notify URL value for this particular transaction
    'hook_url'         => '###HOOK_URL###',
    
    // Date by which the customer must settle the payment
    'due_date'		   => '###DUE_DATE###',
    
    // The reference related to your customer`s invoice of the order.
    'invoice_ref'	   => '###INVOICE_REF###',
    
    // The unique mandate reference of the written SEPA mandate.
    'mandate_ref'	   => '###MANDATE_REF###',
    
    // The start date at which the end-customer allowed Novalnet or the merchant to book from his/her account.
    'mandate_date'	   => '###MANDATE_DATE###',
    
    // The debit reason defines the text on the customer's proof of payment.
    'debit_reason_1'	   => '###DEBIT_REASON_1###',
    'debit_reason_2'	   => '###DEBIT_REASON_2###',
    'debit_reason_3'	   => '###DEBIT_REASON_3###',
    'debit_reason_4'	   => '###DEBIT_REASON_4###',
    
    // The flag to create the token for the payment data
    'create_token'         => 1,
    
    // Processing the transaction with SCA authentication
    'enforce_3d'           => 1,
    
    // Build Payment Data
    'payment_data'     => [
		// Build your payment data based on your selected payment type
		'account_holder' 	=> encrypt_data('###ACCOUNT_HOLDER###', $unique_key),
		'iban'          	=> encrypt_data('###IBAN###', $unique_key),
		'pan_hash'      	=> encrypt_data('###PAN_HASH###', $unique_key),
		'unique_id'     	=> encrypt_data('###UNIQUE_ID###', $unique_key),
		
		// If your server has PCI-DSS compliant for credit card payments, you can directly send the card data (it must be in an encrypted format).
		'card_holder'		=> encrypt_data('###CARD_HOLDER###', $unique_key),
		'card_number'		=> encrypt_data('###CARD_NUMBER###', $unique_key),
		'card_expiry_month'	=> encrypt_data('###CARD_EXPIRY_MONTH###', $unique_key),
		'card_expiry_year'	=> encrypt_data('###CARD_EXPIRY_YEAR###', $unique_key),
		'card_cvc'			=> encrypt_data('###CARD_CVC###', $unique_key)
    ]
];

// Subscription Data
$data['subscription'] = [

    // The interval between each cycle
    'interval'       => '1m',

    // Subscription trial interval if applicable
    'trial_interval' => '3m',

    // Subscription trial interval amount if applicable
    'trial_amount'   => '150'
];

// Instalment data
$data['instalment'] = [

	// The interval between each cycle
	'interval' => '1m',

	// Total number of cycles
	'cycles' => '2'
];

// Marketplace data
$data['marketplace'] = [

	// To submit amount for several affiliates to be booked
	'tx_split' => [
		'2261' => '100',
		'2271' => '120'
	]
];

// Affiliate Data
$data['affiliate'] = [
	
	// To submit shares for several affiliates for the same transaction
	'subvendors'=> [
		'2261' => '100',
		'2271' => '120'
	]
];

// Invoicing Data
$data['invoicing'] = [

	// Total amount (excl. tax) should be mentioned here
    'net_amount'       => 5000,
                       
    // Total amount (incl. tax) should be mentioned here              
    'gross_amount'     => 5000,
    
    // Overall invoice tax percent should be mentioned here
    'tax_percent'      => 2,
                       
    // Overall invoice tax amount should be mentioned here
    'tax_amount'       => 2,
              
    // Individual product details should be mentioned here
    'product_details'  => [
       [
        'code'          => 'P001',
        'name'          => 'Product name',
        'group'         => 'Product group',
        'description'   => 'Product description',
        'unit'          => 2,
        'quantity'      => 2,
        'unit_price'    => 100,
        'total_price'   => 200,
        'tax_amount'    => 1,
        'tax_percent'   => 1,
        'discount'      => 0,
        'note'          => 'Note about the product'
      ]
    ],
    
    // The notification which you wants to provide to the end-customer in invoice PDF. 
    'notice' => [
		'1' => 'Notice 1',
		'2' => 'Notice 2',
		'3' => 'Notice 3'
    ],
    
    // Customize the customer support details here
    'customer_support'  => 'Max Mustermann | Email: support@yourshop.de',
	
	// Custom Invoice number 
	'custom_invoice_no' => 'INV-32'
];

// Custom Data
$data['custom'] = [
	
	// Shopper's selected language in shop
	'lang'      => 'EN',
	
	// Custom parameter's key
	'input1'    => 'your internal reference parameter name',
	
	// Custom parameter's value
	'inputval1' => 'your internal reference parameter value'
];

// Convert the array to JSON string

$json_data = json_encode($data);

// Handle Response
$response = send_request($json_data, $endpoint, $headers);

/**
 * Get unique key
 *
 * @return string
 */
function generate_unique_key()
{
    return substr(rand(10000000, 99999999).rand(10000000, 99999999), 0, 16);
}

/**
 * Encryption process
 * 
 * @param $data
 * @param $unique_key
 * @param $payment_access_key
 *
 * @return string
 */
function encrypt_data($data, $unique_key)
{
	// Encryption process
	global $payment_access_key;

    return htmlentities(base64_encode(openssl_encrypt($data, "aes-256-cbc", $payment_access_key, true, $unique_key)));
}

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, $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);
	
	return $result;
}

?>

Run

Step 5: Handling payment response

Once the customer completes the payment process, Novalnet will return the payment result in an encrypted format. You have to decrypt the result parameters using your Payment access key & generated a random unique key (from step 1).

<?php
/**
 * Decryption process
 * 
 * @param $data
 * @param $uniqid
 * @param $payment_access_key
 *
 * @return string
 */
function decrypt_data($data, $uniqid)
{
    return openssl_decrypt(base64_decode($data),'aes-256-cbc', '###YOUR_PAYMENT_ACCESS_KEY###', true, $uniqid);
}
?>

Decrypt

If you received the redirect URL (result.redirect_url) in the response, please follow the steps (from 2 to 4) mentioned in the >>link<<.