External Check

Risk Management External Check

External Check | Novalnet Docs

Module API is relevant when you want to use the risk modules without entering into the transaction flow. Typical use case includes:

Acquiring a customer's credit score.
Identifying an IP location of an IP.
Verifying if the VAT ID is valid.

And as this API does not involve a transaction flow, no transaction will be created, and your account will be charged based on the per-service usage.

Risk modules available in Novalnet as external API call:

Buergel Concheck Realtime (DE, AT, CH)
Buergel Riskcheck (DE, AT, CH)
Debt Collection Check
IP Country Blockade
Bank Account Check SEPA
Luhn Check
Identity Fraud Check (IFC)
VAT ID Check
Blacklist Check

Header Authentication

To authenticate your module 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 requests must be made through an HTTPS connection along with the header values. Otherwise, the request will fail with authorization error messages.

Your Payment Access Key carries many privileges, so keep them secure! Do not share your secret Payment Access Key in publicly accessible areas such as GitHub, client-side code, etc.

HTTP request headers

X-NN-Access-Key	`base64_encode({PAYMENT_ACCESS_KEY})`
Content-Type	application/json
Accept	application/json
Charset	utf-8

End point URL: https://payport.novalnet.de/v2/module

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

RESULT

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

CURL

-H 'Content-Type: application/json'
-H 'Charset:utf-8'
-H 'Accept: application/json'
-H 'X-NN-Access-Key:###YOUR_ENCODED_PAYMENT_ACCESS_KEY###'

RESULT

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

NODEJS

headers: {
		'Content-Type': 'application/json',
		'Content-Length': Buffer.byteLength(###POSTDATA###),
		'Charset': 'utf-8',
		'Accept': 'application/json',
		'X-NN-Access-Key': '###YOUR_ENCODED_PAYMENT_ACCESS_KEY###'
		},

RESULT

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

PYTHON

HEADERS = {
'Content-Type': 'application/json',
'Charset': 'utf-8',
'Accept': 'application/json',
'X-NN-Access-Key': '###YOUR_ENCODED_PAYMENT_ACCESS_KEY###'
}

RESULT

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

RUBY

request["Content-Type"] = "application/json"
request["Charset"] = "utf-8"
request["Accept"] = "application/json"
request["X-NN-Access-Key"] = "###YOUR_ENCODED_PAYMENT_ACCESS_KEY###"

RESULT

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

req.Header.Add("Content-Type", "application/json")
req.Header.Add("Charset", "utf-8")
req.Header.Add("Accept", "application/json")
req.Header.Add("X-NN-Access-Key", "###YOUR_ENCODED_PAYMENT_ACCESS_KEY###")

RESULT

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

JAVA

.header("Content-Type", "application/json")
.header("Charset", "utf-8")
.header("Accept", "application/json")
.header("X-NN-Access-Key", "###YOUR_ENCODED_PAYMENT_ACCESS_KEY###")

RESULT

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

CSHARP

request.Headers.Add("Charset", "utf-8");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("X-NN-Access-Key", "\"###YOUR_ENCODED_PAYMENT_ACCESS_KEY###\"");

RESULT

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

Parameter List

Each request is separated into so-called objects which indicate an entity

Each parameter is marked with attributes Mandatory, Optional. Based on your necessity, you can use these parameters accordingly.

- Icon denotes the parameter is used on the conditional attribute basis, and hovering on this icon will give you the details about that condition.

- Icon denotes the payment methods supported or relevant to the parameter defined, and hovering on this icon will give you the details of the list of payment methods supported.

module
Object

Parameter

Description

type
String
Mandatory
ACCOUNT_CHECK_SEPA

Specify the Fraud check type.

Possible values:

ACCOUNT_CHECK_SEPA
CC_CHECK
BUERGEL_IDENTCHECK_CONSUMER
BUERGEL_CONCHECK
BUERGEL_CONCHECK_AT
BUERGEL_CONCHECK_CH
BUERGEL_RISKCHECK
BUERGEL_RISKCHECK_AT
BUERGEL_RISKCHECK_CH
VAT_ID_CHECK
IP_COUNTRY_CHECK
COLLECTION_CHECK
BLACKLIST_CHECK

payment_type
String
Conditional
CREDITCARD

Payment types defined at Novalnet. If a value is passed, then the given payment type will be shown as preselected in Novalnet payment page. Refer section for the available payment types.

Possible values:

CREDITCARD
DIRECT_DEBIT_SEPA
INVOICE
PREPAYMENT

payment_data
Object

In this object you have to specify the Customer's payment data information
Hide child object

bic
String
Conditional
CMCIDEDDXXX

BIC (Bank Identifier Code) of the bank account holder

card_number
String
Conditional
XXXXXXXXXXXX0000

Credit/Debit Card number

Note: If your server has PCI-DSS compliant for Credit/Debit Cards, you can directly send the card data in an encrypted format. Refer to the Encryption section to know about the process.

card_expiry_year
Integer
Conditional
2020

Card Expiry year

Note: If your server has PCI-DSS compliant for Credit/Debit Cards, you can directly send the card data in an encrypted format. Refer to the Encryption section to know about the process.

card_expiry_month
Integer
Conditional
12

Card Expiry month

Note: If your server has PCI-DSS compliant for Credit/Debit Cards, you can directly send the card data in an encrypted format. Refer to the Encryption section to know about the process.

merchant
Object

Parameter	Description
signature String Mandatory 7ibc7ob5\|tuJEH3gNbeWJfIHah\|\|nbobljbnmdli0poys\|doU3HJVoym7MQ44qf7cpn7pc	The merchant's project signature is required to process a transaction. It acts as a private key, that can be found logging into Novalnet Admin Portal and by navigating to the following path: Projects -> [SELECT YOUR DESIRED PROJECT] -> API credentials -> API Signature

customer
Object

Parameter

Description

first_name
String
Conditional
Max

Firstname of the customer.

last_name
String
Conditional
Mustermann

Lastname of the customer.

email
String
Conditional
test@novanet.de

Customer's billing email address

birth_date
String
Optional
1992-06-10

Customer's date of birth. The format to be specified is "YYYY-MM-DD"

Note: Mandatory only for B2C for processing guaranteed and installment payments such as GUARANTEED_DIRECT_DEBIT_SEPA, GUARANTEED_INVOICE, INSTALMENT_DIRECT_DEBIT_SEPA, INSTALMENT_INVOICE

gender
String
Optional
u|m|f

Gender of the Customer.

The following values are permitted:

m for "Male"
f for "Female"
u for "Unknown"

vat_id
String
Conditional
DE123456

Organization's VAT ID

customer_ip
String
Conditional
127.0.0.1

Customer's IP address. We recommend you to provide this data, as it is used in fraud checks (for instance - IP BIN check, IP blockade etc.)

billing
Object

In this object you have to specify the Customer's billing information
Hide child object

house_no
String
Conditional
2

Customer's billing house extension

city
String
Conditional
Musterhausen

Customer's city

zip
String
Conditional
12345

Customer's postal code

Note: If there is no postal code, please use ‘-’ as a static value

country_code
String
Conditional
DE

Customer's billing country. The two-character country ISO code as defined in ISO-3166-1 alpha-2

tel
String
Optional
+49 089 123456

Customer's telephone number

company
String
Conditional
ABC GmbH

Organization name

custom
Object

Parameter	Description
lang String Optional EN	Language Code as two characters as per ISO 639-1 standards

module
Object

buergel_score_value
String
Conditional
0 The resultant CRIF Buergel Score value from the fraud check reference_id
String
Conditional
123456789 Module reference id

result
Object

Parameter	Description
status String Mandatory SUCCESS\|FAILURE	Status about the API for the transaction
status_text String Mandatory Successful	Developer-facing message that describes the error encountered and possible steps to correct it.
additional_message String Mandatory Card lost	Additional message about the transaction
status_code Integer Mandatory 100	Status code about the API for the transaction

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [
     
      'type' => 'IP_COUNTRY_CHECK' 
];

$data['customer'] = [

	'customer_ip' => '###CUSTOMER_IP###',
	
	'billing' => [
	
	  'country_code' => 'DE'
	]
];

// Custom Data
$data['custom'] = [

	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

//print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}	
?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [

    'type' => 'ACCOUNT_CHECK_SEPA',
    
    'payment_data' => [
      'iban' => '###IBAN###',
      'bic' => '###BIC###'
    ]
    
];

// Custom Data
$data['custom'] = [
	
	// Merchant's selected language
	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}

?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [

    'type' => 'CC_CHECK',
    
    'payment_data' => [
      'card_number' => '###YOUR_CARD_NUMBER###',
      'card_expiry_month' => '###YOUR_CARD_EXPIRY_MONTH###',
      'card_expiry_year' => '###YOUR_CARD_EXPIRY_YEAR###'
    ] 
];

// Custom Data
$data['custom'] = [
	
	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}

?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature , 
];

$data['customer'] = [

	  'email' => 'test@novalnet.de',
];

$data['module'] = [

	'type' => 'BLACKLIST_CHECK',

	'payment_data' => [
		'iban' => '###IBAN###'
	]
];

// Custom Data
$data['custom'] = [
	// Merchant's selected language
	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}

?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [
     
      'type' => 'BUERGEL_CONCHECK' ,
      'payment_type' => '###PAYMENT_TYPE###'
];

$data['customer'] = [

	'customer_ip' => '###CUSTOMER_IP###',
	// Shopper's first name
    'first_name'  => 'Max',
    
     // Shopper's last name
    'last_name'   => 'Mustermann', 
    
    // Shopper's email
    'email'       => '###YOUR_MAIL###', 
        
    // Shopper's birthdate value YYYY-MM-DD - Decomment it based on your usage
    'birth_date'  => '1992-06-10',
    
    // Shopper's gender - Decomment it based on your usage
    'gender'      => 'u',
    
    'vat_id'      => '###VAT_ID###',

    // Shopper's billing address
    'billing'     => [
    
		'company' => 'ABC GmbH',
		
		// House number
		'house_no'     => '2',
		
		// Street
		'street'       => 'Musterstr',
		
		// City
		'city'         => 'Musterhausen',
		
		// zip
		'zip'          => '1225',
		
		// Country's ISO subscode
		'country_code' => 'DE',
    ]
];

// Custom Data
$data['custom'] = [

	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}	
?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [
     
      'type' => 'BUERGEL_RISKCHECK' ,
      'payment_type' => '###PAYMENT_TYPE###'
];

$data['customer'] = [

	'customer_ip' => '###CUSTOMER_IP###',
	// Shopper's first name
    'first_name'  => 'Max',
    
     // Shopper's last name
    'last_name'   => 'Mustermann', 
    
    // Shopper's email
    'email'       => '###YOUR_MAIL###', 
        
    // Shopper's birthdate value YYYY-MM-DD - Decomment it based on your usage
    'birth_date'  => '1992-06-10',
    
    // Shopper's gender - Decomment it based on your usage
    'gender'      => 'u',
    
    'vat_id'      => '###VAT_ID###',

    // Shopper's billing address
    'billing'     => [
    
		// House number
		'company'     => 'ABC GmbH',
		
		'house_no'     => '2',
		
		// Street
		'street'       => 'Musterstr',
		
		// City
		'city'         => 'Musterhausen',
		
		// zip
		'zip'          => '1225',
		
		// Country's ISO subscode
		'country_code' => 'DE',
		
		// Telephone number
        'tel'           => '+49 089 12256',
        
        // Name of the company
        'company'       => 'ABC GmbH',
    ]
];

// Custom Data
$data['custom'] = [

	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}	
?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [
     
      'type' => 'COLLECTION_CHECK' ,
      'payment_data' => [
        'iban' => '###IBAN###',
        'card_number' => '###CARD_NUMBER###'
    ]
];

// Custom Data
$data['custom'] = [

	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}	
?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [
     
      'type' => 'BUERGEL_IDENTCHECK_CONSUMER',
      'payment_type' => '###PAYMENT_TYPE###'
];

$data['customer'] = [

	'customer_ip' => '###CUSTOMER_IP###',
	
	'billing' => [
	
	  'country_code' => 'DE'
	]
];

// Custom Data
$data['custom'] = [

	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}	
?>

<?php

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

// Need to enter your API signature here
$api_signature 		= '###YOUR_API_SIGNATURE###';

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

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

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

$data = [];

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

    'signature' => $api_signature, 
];

$data['module'] = [
     
      'type' => 'VAT_ID_CHECK' 
];

$data['customer'] = [

	'customer_ip' => '###CUSTOMER_IP###',
	'vat_id' => '###VAT_ID###',
	'first_name'  => 'Max',
    
     // Shopper's last name
    'last_name'   => 'Mustermann', 
    
    // Shopper's email
    'email'       => '###YOUR_MAIL###', 
        
    // Shopper's birthdate value YYYY-MM-DD - Decomment it based on your usage
    'birth_date'  => '1992-06-10',
    
    // Shopper's gender - Decomment it based on your usage
    'gender'      => 'u',

    // Shopper's billing address
    'billing'     => [
    
		// House number
		'house_no'     => '2',
		
		// Street
		'street'       => 'Musterstr',
		
		// City
		'city'         => 'Musterhausen',
		
		// zip
		'zip'          => '1225',
		
		// Country's ISO subscode
		'country_code' => 'DE',
		
		// Telephone number
        'tel'           => '+49 089 12256',
        
        // Name of the company
        'company'       => 'ABC GmbH',
    ]
];

// Custom Data
$data['custom'] = [

	'lang'      => 'EN',
];

// Convert the array to JSON string
$json_data = json_encode($data);

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

print_r($response);

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);
    
    
    curl_setopt($curl, CURLOPT_AUTOREFERER, 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;
}	
?>

JAVA

//package buergel_risk_check;
// sends a request for the Buergel Risk Check for B2B customers to the v2 API

/* List of required libraries (see also the import statements below): 
- commons-logging-1.2.jar    
- httpasyncclient-4.1.5.jar  
- httpclient-4.3.3.jar  
- httpcore-4.4.16.jar   
- httpcore-nio-4.4.16.jar  
- httpmime-4.5.14.jar      
- json-20230227.jar  
- unirest-java-3.9.00.jar
*/

import org.json.JSONArray;
import org.apache.http.auth.*;
import org.apache.http.nio.conn.*; 
import org.apache.http.concurrent.*;
import org.apache.http.nio.reactor.*;
import org.apache.commons.logging.*;
import org.apache.http.entity.mime.content.*; 
import kong.unirest.*;

public class BuergelRiskCheck {
  public void send_test_request() {
    Unirest.config().connectTimeout(1000).socketTimeout(2000);
    HttpResponse<string> response = Unirest.post("https://payport.novalnet.de/v2/module")
      .header("Content-Type", "application/json")
      .header("Charset", "utf-8")
      .header("Accept", "application/json")
      .header("X-NN-Access-Key", "###YOUR_ENCODED_PAYMENT_ACCESS_KEY###")
      .body("{\"merchant\":{\"signature\":\"###YOUR_API_SIGNATURE###\"},\"customer\":{\"customer_ip\":\"###CUSTOMER_IP###\",\"gender\":\"u\", \"first_name\": \"Max\", \"last_name\": \"Mustermann\", \"email\": \"###YOUR_MAIL###\", \"birth_date\":\"1992-06-10\",\"billing\":{\"street\":\"Musterstr\",\"house_no\":\"2\",\"city\":\"Musterhausen\",\"zip\":\"12345\",\"country_code\":\"DE\",\"company\": \"ABC GmbH\",\"tel\":\"+49 089 123456\"}},\"module\":{\"type\":\"BUERGEL_RISKCHECK\",\"payment_type\": \"###PAYMENT_TYPE###\",\"payment_data\":{\"iban\":\"###IBAN###\"}},\"custom\":{\"lang\":\"EN\"}}")
      .asString();
    System.out.println(response.getBody());
  }
  public static void main(String[] args) {
    BuergelRiskCheck requestClient = new BuergelRiskCheck();
    requestClient.send_test_request();
  }

}</string>

JAVA

//package vat_id_check;

/* List of required libraries (see also the import statements below): 
- commons-logging-1.2.jar    
- httpasyncclient-4.1.5.jar  
- httpclient-4.3.3.jar  
- httpcore-4.4.16.jar   
- httpcore-nio-4.4.16.jar  
- httpmime-4.5.14.jar      
- json-20230227.jar  
- unirest-java-3.9.00.jar
*/
// sends a request for the VAT ID check to the v2 API
// test address data taken from: https://www.fakenamegenerator.com/gen-random-gr-gr.php
// test VAT ID from database entry for vendor 4

import org.json.JSONArray;
import org.apache.http.auth.*;
import org.apache.http.nio.conn.*; 
import org.apache.http.concurrent.*;
import org.apache.http.nio.reactor.*;
import org.apache.commons.logging.*;
import org.apache.http.entity.mime.content.*; 
import kong.unirest.*;

public class VATIDCheck {
  public void send_test_request() {
    Unirest.config().connectTimeout(1000).socketTimeout(2000);
    HttpResponse<string> response = Unirest.post("https://payport.novalnet.de/v2/module")
      .header("Content-Type", "application/json")
      .header("Charset", "utf-8")
      .header("Accept", "application/json")
      .header("X-NN-Access-Key", "###YOUR_ENCODED_PAYMENT_ACCESS_KEY###")
      .body("{\"merchant\":{\"signature\":\"###YOUR_API_SIGNATURE###\"},\"customer\":{\"customer_ip\":\"###CUSTOMER_IP###\",\"gender\":\"u\", \"first_name\": \"Max\", \"last_name\": \"Mustermann\", \"email\": \"###YOUR_MAIL###\", \"birth_date\":\"1992-06-10\",\"vat_id\":\"###VAT_ID###\",\"billing\":{\"street\":\"Musterstr\",\"house_no\":\"2\",\"city\":\"Musterhausen\",\"zip\":\"12345\",\"country_code\":\"DE\",\"company\": \"ABC GmbH\",\"tel\":\"+49 089 12256\"}},\"module\":{\"type\":\"VAT_ID_CHECK\"},\"custom\":{\"lang\":\"EN\"}}")
      .asString();
    System.out.println(response.getBody());
  }
  public static void main(String[] args) {
    VATIDCheck requestClient = new VATIDCheck();
    requestClient.send_test_request();
  }

}</string>

External Check

Risk modules available in Novalnet as external API call:

Header Authentication

HTTP request headers

Parameter List

moduleObject

merchantObject

customerObject

customObject

moduleObject

resultObject

module
Object

merchant
Object

customer
Object

custom
Object

module
Object

result
Object