Create | Novalnet Docs

 Create

Here you can pass the amount, currency, subscription cycle and period during the payment transaction This can be up to two different subscription cycle and period with various amounts, for eg: if you have a business where the end customer pays first month amount 20.00 € and then each quartal 50.00 € endlessly as long as the end customer (or merchant) does not cancel this subscription.

This API can be used only when you are using the dynamic subscription in Novalnet

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

URL:
https://payport.novalnet.de/v2/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.

URL:
https://payport.novalnet.de/v2/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
Mandatory
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
Conditional
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
Conditional
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
Optional
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. due_date
String
Optional
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".

payment_data
Object In this object you have to specify the Customer's payment data information
Hide child object
iban
String
Conditional
DE24300209002411761956 IBAN (International Bank Account Number) of the bank account holder bic
String
Conditional
CMCIDEDDXXX BIC (Bank Identifier Code) of the bank account holder card_holder
String
Conditional
Max Mustermann Credit/Debit Card holder

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_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_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. 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. pan_hash
String
Conditional
a7d2j1kh0gfi6e3m98lc4b5151 Alias of the Credit/Debit Cards data, received from Novalnet during the Credit/Debit Card form setup. Please note that this value has to be passed along with the transaction.unique_id to execute a successful Credit/Debit Cards transaction.

Note: Refer the section Client side Tokenization to know more details about the handling. unique_id
String
Conditional
f0g81c69kmi4a3e5bh72ljd Unique identifier generated with the payment data which is received from Novalnet during the Credit/Debit Card form setup. Please note that this value has to be passed along with the transaction.pan_hash to execute a successful Credit/Debit Cards transaction.

Note: Refer the section Client side Tokenization to know more details about the handling. token
String
Conditional
RcBw2w00a02c-R22w22w22wNJV-V22wV22w10k22wB18sBR06g00aD04eZ12m10k The payment token would have been delivered during your initial successful payment request of the corresponding customer (when using transaction.create_token). This token replaces the customer's payment data and hence preventing the need to get the payment details from the customer again.

You will receive the payment token from Novalnet in token parameter in the child object payment_data of the main object transaction (transaction.payment_data.token), through the following options:

  • In the real-time response of your payment call (Direct API only).
  • In the Novalnet webhook notification call




wallet_token
String
Conditional
xVXoBTV-avVtXZV-wyPgqJLJauHkHaBNgVgsmTLgoTgkZVcckqXCBiFkmJgowsyueRaZmkyFocNyBowZ Alias of the Apple Pay/Google Pay payment data, received from Novalnet during the authentication from the payment sheet. Only when this value is passed to the Novalnet server, the Apple Pay/Google Pay execution will be successful. account_number
Integer
Mandatory
1234567830 Account Number of the bank account holder. routing_number
Integer
Mandatory
031200730 Routing Number of the bank account holder. card_cvc
Integer
Conditional
123 Card Verification Code 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.
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. 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.




call_n_pay
Integer
Optional
1 Passing this parameter with value 1 enables Call N Pay feature, Shoppers follow easy voice instructions on a phone call to complete payment. 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 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.
subscription
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.

bank_details
Object This object contains the bank details to which the customer has to transfer the transaction amount
Hide child object
bank_code
Integer
Conditional
74020100 Bank code bank_name
String
Conditional
Raiffeisenlandesbank O Zndl Sddeutschland Bank name bank_place
String
Conditional
Passau Place of the bank account_holder
String
Conditional
Max Mustermann Name of the bank account holder iban
String
Conditional
DE24300209002411761956 IBAN (International Bank Account Number) of the bank account holder bic
String
Optional
CMCIDEDDXXX BIC (Bank Identifier Code) of the bank account holder qr_image
String
Conditional
https://nnt.ag/epcqr/15339600072003130.png This parameter provides a hosted link to a dynamically generated QR code for applicable Pay-By-Invoice transactions. The QR code is created for all pending, authorized, and successful transactions (including subscriptions and instalment renewals) when the transaction amount is greater than zero.

For marketplace transactions, a single QR code is generated for the total order amount. If the transaction amount or order number is modified, the QR code is automatically regenerated and updated on the same link to always reflect the latest transaction details.
fraud_check
Object This objects contains the Fraud check details, for example: Buergal score
Hide child object
trader_name
String
Mandatory
Mustermann GmbH Trader name belonging to this VAT ID trader_address
String
Mandatory
Musterstr, 2, 12345, Musterhausen Trader address belonging to this VAT ID buergel_score_value
String
Optional
0 The resultant CRIF Buergel Score value from the fraud check
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. tid_payment
Integer
Optional
12997200005200690 The original payment TID which will be sent during the transaction response status_code
Integer
Mandatory
100 Status code for the transaction authorization
Object
Hide child object
auto_action
String
Conditional
CAPTURE|VOID It contains the action (CAPTURE/VOID) going to be carried out on the expiry of the authorization.Note: Merchant can customize these action on Novalnet Admin Portal.
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".

invoice_no
String
Optional
852963 Unique identifier invoice number from the shop qr_image
String
Conditional
https://nnt.ag/qr/ux631hb9.png The QR image of the shortened URL 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.
customer
Object
customer_ip
String
Mandatory
127.0.0.1 Customer's IP address customer_no
String
Optional
12345 Customer's unique identifier from the shop birth_date
String
Conditional
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 This object contains 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 city
String
Optional
Musterhausen Customer's shipping city zip
String
Optional
12345 Customer's postal code 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: 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
Conditional
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
Optional
fedgrgst5653653hdgfsvgdsf622627e Customer's session ID from the shop no_nc
Integer
Optional
1 This parameter will be returned, If you opted for no_nc option
subscription
Object
marketplace
Object
invoicing
Object
custom
Object
call_n_pay
Object