Integration Options Hosted Payment Page Parameter Reference
Hosted Parameter Reference | Novalnet Docs

  Parameter Reference

The Novalnet API is organized around JSON-RPC. Our API has predictable resource-oriented URLs, accepts application/json request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Header Authentication

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

  1. 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.
  2. The Payment Access Key should be encoded using a variant of Base64.
  3. 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.

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(s)

Please use the below URL(s) as per your business process and requirements:

Payment

This action immediately books the desired amount. The payment API is equivalent of doing an authorization and capture all at once

End point URL:

https://payport.novalnet.de/v2/seamless/payment

Authorize

As the name suggests, this action only performs the basic authorization and will not book the amount immediately. A Payment action - Capture is required to book the authorized amount later.

End point URL:


https://payport.novalnet.de/v2/seamless/authorize

Parameter List

Each payment request has been 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.

Each parameter is marked with attributes Mandatory, Conditional, 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.
merchant
Object
customer
Object
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.) customer_no
String
Optional
12345 The customer's unique identifier from the shop. The maximum length of this parameter is 20 characters. If you need to provide more than 20 characters for handling or passing customer numbers, please use the custom objects provided below via the input1..7 and inputval1..7 parameters. The use of custom object transmission is solely for facilitating the exchange of customer numbers. Please note that using this option will not allow Novalnet to assign the customer_no internally.

Note: If you have already processed a successful transaction with the same customer_no, you do not need to send the mandatory billing customer fields, simply passing the customer_no is sufficient. For more details, refer to this section.

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

tel
String
Optional
+49 089 123456 Customer's telephone number mobile
String
Optional
+491747781423 Customer's mobile number fax
String
Optional
+49 89 654321 Customer's fax number shipping
Object In this object you have to specify the Customer's shipping information
Hide child object
first_name
String
Optional
Max Customer's shipping firstname last_name
String
Optional
Mustermann Customer's shipping lastname email
String
Optional
test@novanet.de Customer's shipping email address company
String
Optional
ABC GmbH Organization name of the shipping address house_no
String
Optional
2 Customer's shipping house extension street
String
Optional
Musterstr Customer's shipping street name

Note: The house_no parameter mentioned above can also be passed along with the street parameter by using anyone of the following separators "/", "-", ".", ","

city
String
Optional
Musterhausen Customer's shipping city zip
String
Optional
12345 Customer`s shipping postal code

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

country_code
String
Optional
DE Customer's shipping country. The two-character country ISO code as defined in ISO-3166-1 alpha-2 tel
String
Optional
+49 089 123456 Customer's shipping telephone number mobile
String
Optional
+491747781423 Customer's shipping mobile number state
String
Optional
Berlin The customer's shipping state identifies a specific region within a country. Novalnet currently supports this parameter in three formats:
  • ISO 3166-2 State Codes: Provide the state using the state code according to the ISO 3166-2 standard for seamless transmission during payment processing. For example, state codes (such as "BE" for Berlin) are typically 2 characters long.
  • Country Code Format: The state code in country code format for Germany is "DE-" followed by the 2-letter state code (e.g., "DE-BE" for Berlin, "DE-HH" for Hamburg).
  • Full State Names: Full state names can be provided using string characters with a maximum length of up to 50 characters (e.g., "Berlin", "Hamburg").
Note: Allowed characters are alphanumeric, numbers, space, hyphen, apostrophe, period and other accented characters such as umlauts, Latin characters. district
String
Optional
Pankow The customer's district from the shipping information, which identifies a specific administrative region within a state or province.

Note: Allowed characters are alphanumeric, numbers, space, hyphen, apostrophe, period and other accented characters such as umlauts, Latin characters.

vat_id
String
Optional
DE123456 Organization's VAT ID tax_id
String
Optional
123/123/123 The parameter represents the unique tax identification number assigned to a customer or company. This is essential for compliance with tax regulations and enables accurate identification of businesses in B2B transactions.Note: Allowed characters are alphanumeric, numbers, space, hyphen and period. reg_no
String
Optional
HRB1234 Organization's registration number session
String
Conditional
fedgrgst5653653hdgfsvgdsf622627e Customer's session ID from the shop

Note: The fraud check session check works based on the input of this parameter

no_nc
Integer
Optional
1 Passing this parameter with value 1 will allow you to not send the mandatory parameters like first_name, last_name, street, city, zip, country_code. Either the customer's email or the mobile number is sufficient to make a transaction.

Note: Due to legal/security reasons, this option can only be allowed after clearing the compliance of each project at Novalnet through the Novalnet compliance team.

transaction
Object
order_no
String
Conditional
123456789 Order's unique identifier from the shop. The maximum length of this parameter is 50 characters, if you want to provide more than 50 characters then please use the custom object given below through the parameters input1..7 and inputval1..7. invoice_ref
String
Optional
BNR-14-213257 The reference related to your customer's invoice of the order. The maximum length of this parameter is 50 characters, if you want to provide more than 50 characters then please use the custom object given below through the parameters input1..7 and inputval1..7 create_token
Integer
Optional
1 If this parameter is set to 1 and provided with a customer.customer_no, then the customer's payment data will be stored as tokens for future purchases. Know more about tokenization here. payment_data
Object In this object you have to specify the Customer's payment data information
Hide child object
hook_url
String
Conditional
https://www.demoshop.de/webhook Notification/Webhook URL to receive the information about the notification events that occurs for each transaction. To know more about the notification and events, refer this section. verify_payment_data
Integer
Optional
1 This is to verify if given payment data of user has already a successful booking before and to decide the payment status accordingly, from the value passed in this parameter.

Any one of the following value must be passed in the transaction.verify_payment_data parameter, for the decision making if the payment data is already used:

  • 1 for "Processing the result as it is"
  • 2 for "Putting the transaction onhold (here only the authorization is performed) and then to make an action later"
  • 3 for "Rejecting the transaction"

Refer the section verify payment data to know more details about the handling.




due_dates
Object
Optional
{"INVOICE":"2026-09-03","PREPAYMENT":"2021-08-16","DIRECT_DEBIT_SEPA":"2026-09-03"} For credit transfers: Date by which the customer must settle the payment.
For SEPA Direct Debit: The date by which the customer must be debited by their bank. If this field is left empty, Novalnet will initiate the debit on the third working day after the transaction date.

  • 3 - 14 for Direct Debit SEPA
  • >7 for Invoice and Prepayment
Note: The format to be specified is "YYYY-MM-DD".

mandate_ref
String
Optional
NN-12345678901234567 Unique mandate reference of the written SEPA mandate, this reference will be displayed in the end-customer's bank statement. If not provided, by default TID will be considered mandate_date
String
Optional
2026-08-20 Start date at which the end-customer allowed Novalnet or the merchant to book from his/her account. The date of signature of SEPA mandate. If not provided, by default the transaction date will be considered.

Note: The format to be specified is "YYYY-MM-DD".

enforce_3d
Integer
Optional
1 If you wish to process the SCA authentication for the Credit/Debit Cards, use this parameter

The following values are permitted:
  • 1 for "Processing the transaction with SCA authentication"

Note: By default, we will do the SCA authentication for the Credit/Debit Cards(cards within Europe region).



dynamic_descriptor
String
Optional
www.yourshop.com The dynamic descriptor defines the text on the shopper’s proof of payment (e.g. credit statement record and similar).

Note: The value can have a maximum length of 20 chars. Longer values will be truncated, and the value must not contain umlauts, special characters (like < > * '") or spaces.

invoice_no
String
Optional
852963 Unique identifier invoice number from the shop transfer_type
String
Optional
DEBIT Specify the transfer type CREDIT or DEBIT.

  • CREDIT - Debited from Marketplace and Credited to Affiliate or subvendor
  • DEBIT - Debited from Affiliate or subvendor and credited to Marketplace
By default, if this parameter is not passed, the transfer type will be DEBIT debit_reason_1..5
String
Optional
www.test.com The debit reason defines the text on the customer's proof of payment (e.g., bank statement records and similar).Note: Each debit reason can have a maximum of 27 characters, with an overall length of 140 characters for all five debit reasons. The debit reason is case-sensitive, allowing characters from a to z, A to Z, and 0 to 9. Only space and hyphens are allowed, while other special characters and symbols are taken as spaces.
hosted_page
Object
subscription
Object
instalment
Object
marketplace
Object
affiliate
Object
invoicing
Object
customer_support
String
Optional
Max Mustermann | Email: support@yourshop.de Customize the customer support details here notice
Object
Optional
{'1' : 'Notice 1', '2' : 'Notice 2', '3' : 'Notice 3'} The notification which you wants to provide to the end-customer in invoice PDF. You can add upto three notifications per transaction. custom_invoice_no
String
Optional
INV-32 A customized invoice number which will be used instead of the default system generated invoice number.

Note: The value should be unique for each invoice generation request. send_invoice_pdf
Integer
Conditional
1 The end customer will receive an Invoice PDF as an attachment in the order confirmation email.

Note: By default, the end customer will receive the Invoice PDF in a separate email.
  • 1 - send the Invoice PDF in the end customer's confirmation email (from Novalnet)
  • 0 - skip the delivery of the Invoice PDF in the confirmation email.
custom
Object
cart_info
Object
result
Object
transaction
Object
marker
String
Optional
DEF20140103987 A unique tag used in the APIs to group specific transactions across customers, projects for statistical overview or filtering in reporting. For example, if the transactions that were placed in the store with a particular offer need to be grouped separately, then passing this parameter with a value of "FESTIVALOFFER" can allow you to list these transactions distinctively. identifiers
Multi-Dimensional Array
The identifiers is used to tag and group transactions in a flexible way, similar to the marker parameter but with support for multiple categories. Each identifier consists of a type and a value, allowing transactions to be grouped or filtered across different dimensions (e.g., offers, customer segments, projects).
Hide child object
value
String
Conditional
FESTIVAL|B2B Defines the corresponding identifier within the selected type.

  • Ex: If type = "OFFER", then value could be "FESTIVAL".
  • Ex: If type = "CUSTOMER_TYPE", then value could be "B2B".
Note: Allowed characters include alphanumeric letters (A–Z, a–z, 0–9), underscores (_), hyphens (-), spaces, periods (.), and accented characters such as umlauts (ä, ö, ü). The maximum permitted length of this parameter is 70 characters.

hook_url
String
Conditional
https://www.demoshop.de/webhook Notification/Webhook URL to receive the information about the notification events that occurs for each transaction. To know more about the notification and events, refer this section. link_expiry
String
Conditional
2026-09-10 23:43:04 The expiry period of the shortened URL. The format to be specified is "YYYY-MM-DD HH:MM:SS".

Note: By default, the shortened URL will be valid for 21 days.

qr_image
String
Conditional
https://nnt.ag/qr/ux631hb9.png The QR image of the shortened URL mandate_ref
String
Optional
NN-12345678901234567 Unique mandate reference of the written SEPA mandate, this reference will be displayed in the end-customer's bank statement. If not provided, by default TID will be considered transfer_type
String
Optional
DEBIT Specify the transfer type CREDIT or DEBIT.

  • CREDIT - Debited from Marketplace and Credited to Affiliate or subvendor
  • DEBIT - Debited from Affiliate or subvendor and credited to Marketplace
By default, if this parameter is not passed, the transfer type will be DEBIT debit_reason_1..5
String
Optional
www.test.com The debit reason defines the text on the customer's proof of payment (e.g., bank statement records and similar).Note: Each debit reason can have a maximum of 27 characters, with an overall length of 140 characters for all five debit reasons. The debit reason is case-sensitive, allowing characters from a to z, A to Z, and 0 to 9. Only space and hyphens are allowed, while other special characters and symbols are taken as spaces.