On occurrence of each transaction creation or status change at Novalnet, the Novalnet system will also send all the transaction details to your webhook endpoint. The following parameters will be sent with their respective values for every payment (if successful or not) as well as for every follow up transaction, (for example: credit entry, chargeback, collection payment, etc.) and also for subscription/instalment related actions.
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.The decision making about the notification result will solely depend on the parameter status under the object result. The parameter can take up either of the values SUCCESS or FAILURE
|
Parameter
|
Description
|
|---|---|
|
type
String Mandatory PAYMENT|TRANSACTION_CAPTURE|TRANSACTION_CANCEL|TRANSACTION_REFUND|TRANSACTION_UPDATE|SUBSCRIPTION_CANCEL|SUBSCRIPTION_UPDATE|SUBSCRIPTION_SUSPEND|SUBSCRIPTION_REACTIVATE|CREDIT|CHARGEBACK|INSTALMENT|RENEWAL|AFFILIATE_CREATION|AFFILIATE_ACTIVATION|INSTALMENT_CANCEL|PAYMENT_REMINDER|COLLECTION|CALL_N_PAY|PAY_BY_LINK|PAYMENT_LINK_UPDATE|ACCOUNT_ACTIVATION|PRODUCT_ACTIVATION |
Webhook events are the triggers performed whenever there is an action related to a transaction, subscription and affiliates. Refer this section for the event type details. |
|
checksum
String Mandatory dea695d6f66a69da17fe9716efe4ad0a24849b752e576433b65b1d122441c59a |
It used to authenticate the notification/redirection response |
|
tid
Integer Mandatory 14160600009826120 |
The TID which is relevant to this event. |
|
parent_tid
Integer Conditional 14160600009825220 |
During the course of followup events like chargebacks, credit entry etc.., this field will contain the value of the original/initial transaction TID. |
|
Parameter
|
Description
|
||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
tid
Integer Mandatory 12997200005200690 |
17 digit unique Novalnet transaction ID | ||||||||||||||||
|
status
String Mandatory PENDING|CONFIRMED|ON_HOLD|FAILURE|DEACTIVATED |
The current status of the payment | ||||||||||||||||
|
payment_type
String Mandatory CREDITCARD |
Transaction's Payment type (defined in Novalnet). Refer this section for the payment type details. | ||||||||||||||||
|
amount
Integer Conditional 522 |
The total amount to be charged from the customer includes the line items, tax, shipping and additional costs (in minor units), e.g., Euro in Eurocents (5,22 € = 522). Note: For zero amount booking feature, set amount to 0 (zero). |
||||||||||||||||
|
currency
String Conditional EUR |
The currency in which the transaction is being processed. The three-character currency code as defined in ISO-4217. | ||||||||||||||||
|
order_no
String Conditional 123456789 |
Order's unique identifier received from the shop | ||||||||||||||||
|
test_mode
Integer Mandatory 0 |
Denotes the processing mode of the transaction. Possible values:
|
||||||||||||||||
|
date
String Conditional 2026-03-12 06:11:17 |
Transaction date (incl. time) Format: YYYY-MM-DD HH:MM:SS |
||||||||||||||||
|
txn_secret
String Conditional fd77014683544a21ed47d468fa24e27b |
Transaction secret is a temporary identifier for the payment types with the redirect flow and it travels across the transaction, useful in verifying the payment result | ||||||||||||||||
|
due_date
String Optional 2026-03-26 |
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.
|
||||||||||||||||
|
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 | ||||||||||||||||
|
reason
String Optional Reason |
The reason for the credit entry/chargeback/return debit transaction | ||||||||||||||||
|
reason_code
String Optional M006 |
The reason code for the credit entry/chargeback/return debit transaction | ||||||||||||||||
|
last_success_tid
Integer Optional 14149400012624203 |
Upon successful execution of the verify payment data check, the previously used payment data's TID will also be returned here if found. Refer the section verify payment data to know more details about the handling. |
||||||||||||||||
|
payment_data Object |
This objects contains the Customer's secured Payment data information Hide child 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 |
||||||||||||||||
|
|||||||||||||||||
|
bank_details Object |
This object contains the bank details to which the customer has to transfer the transaction amount Hide child object |
||||||||||||||||
|
|
|||||||||||||||||
|
fraud_check Object |
This objects contains the Fraud check details, for example: Buergal score Hide child object |
||||||||||||||||
|
|
|||||||||||||||||
|
partner_payment_reference
Integer Conditional 999999919 |
The payment reference for the Multibanco payment type. Using this reference, the customer pays in online portal or in the Multibanco ATM to complete the purchase | ||||||||||||||||
|
service_supplier_id
Integer Conditional 11854 |
Service supplier ID from Multibanco | ||||||||||||||||
|
credit_details Object |
Hide child object |
||||||||||||||||
|
|||||||||||||||||
|
status_code
Integer Mandatory 100 |
Status code for the transaction | ||||||||||||||||
|
order_date
String Conditional 2021-06-10 |
Original purchase date, for which the cashback or transaction is being processed Note: The format to be specified is "YYYY-MM-DD". |
||||||||||||||||
|
order_amount
Integer Conditional 2000 |
Original purchase amount, for which the cashback or transaction is being processed | ||||||||||||||||
|
order_reference
String Conditional XXXYYYZZZ |
Original purchase reference or order number, for which the cashback or transaction is being processed | ||||||||||||||||
|
authorization Object |
Hide child object |
||||||||||||||||
|
|
|||||||||||||||||
|
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-03-12 |
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 | ||||||||||||||||
|
transfer_type
String Optional DEBIT |
Specify the transfer type CREDIT or DEBIT.
|
||||||||||||||||
|
qr_image
String Conditional https://nnt.ag/qr/ux631hb9.png |
The QR image of the shortened URL | ||||||||||||||||
|
update_type
String Optional STATUS|AMOUNT|DUE_DATE|AMOUNT_DUE_DATE|PAYMENT_DATA |
The update_type provided for change of the status, amount/ due date and payment data of the transaction. | ||||||||||||||||
|
link_expiry
String Conditional 2020-04-30 23:59:59 |
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. |
||||||||||||||||
|
refund Object |
Hide child object |
||||||||||||||||
|
|||||||||||||||||
|
refunded_amount
Integer Conditional 100 |
Total refunded amount | ||||||||||||||||
|
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. | ||||||||||||||||
|
credit_reason_1..5
String Optional www.test.com |
The credit reason defines the text on the customer's proof of payment (e.g., bank statement records and similar).Note: Each credit reason can have a maximum of 27 characters, with an overall length of 140 characters for all five credit reason. The credit 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. | ||||||||||||||||
|
Parameter
|
Description
|
||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
gender
String Optional u|m|f |
Customer's gender Possible values:
|
||||||||||||||||||||||||||||||
|
first_name
String Mandatory Max |
Firstname of the customer. | ||||||||||||||||||||||||||||||
|
last_name
String Mandatory Mustermann |
Lastname of the customer. | ||||||||||||||||||||||||||||||
|
email
String Mandatory test@novanet.de |
Customer's billing email address | ||||||||||||||||||||||||||||||
|
billing Object |
This object contains the customer's billing information Hide child 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 |
||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||
|
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 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 | ||||||||||||||||||||||||||||||
|
Parameter
|
Description
|
|---|---|
|
subs_id
Integer Mandatory 12345678 |
A unique ID generated for the subscription in Novalnet |
|
next_cycle_date
String Conditional 2026-04-11 06:11:17 |
The next recurring cycle date |
|
tid
Integer Mandatory 12997200005200690 |
17 digit unique Novalnet transaction ID |
|
payment_type
String Conditional CREDITCARD |
Transaction's Payment type (defined in Novalnet). Refer this section for the payment type details. |
|
amount
Integer Conditional 522 |
The amount to be booked for the subscription (in minor units), e.g.:- Euro in Eurocents (5,22 € = 522). |
|
currency
String Conditional EUR |
The currency in which the transaction is being processed. The three-character currency code as defined in ISO-4217. |
|
expiry_date
String Optional 2026-09-12 |
Date by which the subscription should end Note: The format to be specified is "YYYY-MM-DD". |
|
status
String Optional ACTIVE|INACTIVE|SUSPENDED|PENDING |
The current status of the subscription. The possible values are ACTIVE|INACTIVE|SUSPENDED|PENDING. |
|
update_type
String Optional STATUS|RENEWAL_DATE|RENEWAL_AMOUNT|PAYMENT_DATA |
The update_type provided for change of the status, amount, next_cycle_date and payment_data of the subscription |
|
cancel_type
String Optional EXPLICIT | CHARGEBACK | RENEWAL_ERROR |
Mode through which the subscription was cancelled.
|
|
reactivate_type
String Optional EXPLICIT|CREDIT|PAYMENT_UPDATE |
Reactivate type to identify the reason for activating the existing subscription.
|
|
Parameter
|
Description
|
|---|---|
|
next_cycle_date
String Conditional 2026-04-11 06:11:17 |
The next instalment cycle date |
|
cycle_amount
Integer Mandatory 2778 |
The instalment cycle amount |
|
cycles_executed
Integer Conditional 2 |
The number of instalment cycles executed at this point |
|
pending_cycles
Integer Conditional 4 |
The number of instalment cycles remaining to be executed |
|
cycle_dates
String Conditional {"1":"2026-03-12 06:11:17","2":"2026-04-12 06:11:17","3":"2026-05-12 06:11:17"} |
The instalment cycle dates |
|
currency
String Optional EUR |
The currency in which the transaction is being processed. The three-character currency code as defined in ISO-4217. |
|
Parameter
|
Description
|
|---|---|
|
input1..7
String Optional psp |
Arbitrary key-value pairs that can be specified when booking and to be easily transferred back to the booking |
|
inputval1..7
String Optional novalnet |
Arbitrary key-value pairs that can be specified when booking and to be easily transferred back to the booking |
|
Parameter
|
Description
|
|---|---|
|
vendor
Integer Mandatory 4 |
Your Merchant ID |
|
project
Integer Mandatory 6120 |
Your Project ID |
|
project_name
String Mandatory Demo Shop |
Your Project name |
|
project_url
String Mandatory https://demo.novalnet.de |
Your Project URL |
|
activation_date
String Mandatory 2021-02-14, 17:33:14 |
Date and time when the account is activated. |
|
reference
String Mandatory TESTREF |
Your own unique identifier value of the account. |
|
Parameter
|
Description
|
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
vendor
Integer Mandatory 4342 |
Value for the new creation of an merchant/affiliate account at Novalnet | ||||||||||||
|
reference
Integer Optional ABC123456 |
Your own unique identifier value of the affiliate | ||||||||||||
|
first_name
String Mandatory Max |
Affiliate's first name | ||||||||||||
|
last_name
String Mandatory Mustermunn |
Affiliate's last name | ||||||||||||
|
email
String Mandatory test@test.de |
Affiliate's email | ||||||||||||
|
gender
String Mandatory m|f|u |
Affiliate's gender | ||||||||||||
|
tel
String Optional +49 089 123456 |
Affiliate's Telephone no. | ||||||||||||
|
mobile
String Optional +491747781423 |
Affiliate's Mobile no. | ||||||||||||
|
fax
String Optional +49 089 123456 |
Affiliate's Fax no. | ||||||||||||
|
company
String Optional Mustermann GmbH |
Organization name | ||||||||||||
|
company_email
String Optional test@test.de |
Affiliate's company email address | ||||||||||||
|
vat_id
String Optional TAXIDNO1423TEX5 |
Affiliate's company VAT ID | ||||||||||||
|
account_holder
String Optional test max |
Affiliate's bank account holder name. Bank account holder (is a combination of first and last name, in case there is no given entry for this) | ||||||||||||
|
address Object |
Hide child object |
||||||||||||
|
|||||||||||||
|
activation_date
String Mandatory 2019-07-26, 17:33:14 |
Date and time when the affiliate account is activated | ||||||||||||
|
Parameter
|
Description
|
|---|---|
|
amount
Integer Conditional 2100 |
Amount represents the cumulative value that includes principal and relevant claim fees/charges. |
|
claim_amount
Integer Conditional 1500 |
Represent the principal amount that was cancelled. |
|
claim_charges
Integer Conditional 400 |
Claim charges represent either return debit or chargeback amount that was cancelled |
|
claim_fee
Integer Conditional 200 |
Charges cancelled for sending payment reminders via post, email, or other additional services. |
|
currency
String Conditional EUR |
The currency in which the transaction is being processed. The three-character currency code as defined in ISO-4217. |
|
date
String Conditional 2021-12-14 |
Mentions the due date to settle a payment. |
|
due_date
String Optional 2020-04-14 |
Reminder due date |
|
Parameter
|
Description
|
|---|---|
|
amount
Integer Conditional 2100 |
The amount represents the cumulative value, including the principal claim and all associated fees or charges that have been cancelled |
|
claim_amount
Integer Conditional 1500 |
Represent the principal amount that was cancelled. |
|
claim_charges
Integer Conditional 400 |
Claim charges represent either return debit or chargeback amount that was cancelled |
|
claim_fee
Integer Conditional 200 |
Charges cancelled for sending payment reminders via post, email, or other additional services. |
|
currency
String Conditional EUR |
The currency in which the transaction is being processed. The three-character currency code as defined in ISO-4217. |
|
date
String Conditional 2021-12-14 |
The Date on which the case is submitted to the collection agency. |
|
reference
String Conditional 000025-F00002774 |
Reference number for the collection process |
|
status_text
String Conditional Collection in progress |
Current status of the collection process |
|
Parameter
|
Description
|
|---|---|
|
id
Integer Mandatory 14 |
The ID of the project. |
|
name
String Mandatory OXID DEMO SHOP |
The project name of the specific ID. |
|
url
String Mandatory https://oxid.novalnet.de |
The project URL of the project. |
|
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 |
|
activation_date
String Mandatory 2021-05-26, 17:33:14 |
Date and time when the project account is activated |
|
reference
String Mandatory 1234581a67b7542122c |
Credit reference given by end customer during the bank transfer |
|
Parameter
|
Description
|
|---|---|
|
id
Integer Mandatory 30 |
Your Tariff ID of the project |
|
name
String Mandatory OXID DEMO Shop Betrag |
Your Tariff Name of the project |
|
currency
String Mandatory EUR |
Your Tariff Currency of the project |
|
type
String Mandatory ONE_TIME_PAYMENT_WITH_PASSED_TARIFF |
Transaction's Payment type (defined in Novalnet). Refer this section for the payment type details. |
|
Parameter
|
Description
|
|---|---|
|
link_id
String Mandatory 40s086j1aaaaebfj |
A unique identifier for the payment link. This value is available in the Pay by Link API response (transaction.txn_secret). |
|
status
String Conditional ACTIVE|EXPIRED|DEACTIVATED |
Status of the generated payment link.The following values to be returned:
|
|
link_expiry
Integer Conditional 2026-06-10 06:11:17 |
The expiry date of the payment link. The returned date format is YYYY-MM-DD HH:MM:SS |