Direct API

Direct API Integration enables seamless communication between your server and Novalnet’s server. This method provides a high level of control and flexibility for handling transactions and managing payment processes. By using the Direct API, you can control every aspect of transaction handling and data transmission. This allows you to offer payment methods and features tailored to your business needs and customize the payment experience according to your requirements.

If you process credit or debit card payments via the Direct API, Novalnet will handle all PCI-DSS compliance requirements for you. However, if you are already a PCI-regulated entity and need to submit raw credit card data, please contact technic@novalnet.de for further instructions.

How does it work?

For a typical direct API integration flow:

Retrieve Enabled Payment Methods:
- Use the /merchant/details API in the Novalnet Admin Portal to get a list of enabled payment methods for your account. Please note that this is an optional step and if you are already sure about the payment buttons or payment method options you want to offer, you can skip to the third step.
Display Payment Methods:
- Based on the response from Step 1, display the available payment methods on your checkout page.
Collect Necessary Prerequisite Data:
- Before making a direct API request, ensure you gather all required information to complete the transaction successfully. Payment methods such as credit/debit cards or digital wallets like Apple Pay or Google Pay may require an additional preliminary step to collect card details or secure information from the customer before processing the payment. Please refer to the relevant payment method integration documentation for guidance on implementing these additional steps.
Collect the Necessary Customer and Order-Related Information:
- For various payment-related processes, ensure you have prepared the following data: customer name, billing address, customer number, order amount, currency, and order number. Note that not all parameters are mandatory. Refer to the documentation for a complete list of parameters and determine which ones are relevant based on your business needs.
Initiate the API Call:
- Once you have prepared the necessary parameters, you can initiate a payment request to the Novalnet server for processing. The Direct API supports two payment flows depending on the payment method: direct or redirected payment mode.
  - Direct Payment Methods: Methods such as Direct Debit SEPA or Purchase by Invoice do not require additional authentication steps or explicit login. These payments are processed directly without further customer interaction.
  - Redirection Payment Methods: Methods like online bank transfers require the customer to log in to their bank account to complete the transfer. For these methods, you must include additional parameters such as transaction.return_url and transaction.error_return_url to specify where the customer should be redirected after the payment process. For complete handling of redirection payment methods, refer to the provided link for more information.
- Additionally, you can choose between the /payment or /authorize endpoints depending on whether you need to collect the funds immediately or later. The /payment endpoint processes the payment immediately, while the /authorize endpoint reserves the funds and allows for capture at a later time.
Handle Notification Webhooks:
- Process and respond to notification webhooks to keep your system updated with the latest transaction details. Ensure that your system correctly interprets and acts on the information provided in the webhook notifications to maintain accurate and current transaction records.

How to implement?

A set of API endpoints that allow you to perform the payment actions.

Base URL: https://payport.novalnet.de/v2

Action	Endpoint	Description
Payment	/payment	This action immediately books the desired amount. The payment API is equivalent of doing an authorization and capture all at once
Authorize	/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.
Transaction Capture	/transaction/capture	This action collects the funds due from the completed authorizations
Transaction Refund	/transaction/refund	This action returns funds that were already collected by a Payment or a Capture transaction
Transaction Update	/transaction/update	This action will update the existing transaction's attributes like amount, Due date, order number, etc.,
Transaction Cancel	/transaction/cancel	This action is used to avoid collecting the funds from previously completed authorizations
Transaction Details	/transaction/details	Retrieve all the information related to the transaction using the unique identifier from Novalnet - transaction ID (TID).
Subscription Update	/subscription/update	This action will update the existing subscription's attributes like payment method, amount or next recurring date.
Subscription Suspend	/subscription/suspend	This action will pause the existing subscription.
Subscription Reactivate	/subscription/reactivate	This action will reactivate the existing subscription which has been suspended before.
Subscription Cancel	/subscription/cancel	This action will cancel the existing subscription.
Merchant Details	/merchant/details	This action will return the enabled payment method in Novalnet along with the particular merchant details
Instalment Cancel	/instalment/cancel	This action will cancel the existing instalment.
End-customer invoicing	/transaction/invoice	This action is used to create the Customer Invoice pdf generation.
Webhook Configure	/webhook/configure	This action is used to configure webhook URL for notification handling.
Affiliate Create	/affiliate/create	As the name suggests, this action will create the affiliate vendor for the corresponding owner
Customer Update	/customer/update	This action will update a customer's details for all their existing transactions
Module	/module	This action is used where the fraud module is activated without entering into the transaction flow.
Transaction List	/transaction/list	Retrieve all the information related to the transaction using the unique identifier from your shop/interface - order number. Order number-based retrieval is done within the project scope, and all transactions mapped to that order number will be returned. The order number search can retrieve a maximum of 30 recent transactions linked to that order.
Paymentlink update	/payment_link/update	The Payment Link Update API allows you to change the link status, expiry date and amount to be booked until payment is made.
Payment Token Delete	/token/delete	This action is used to delete the existing payment token.
BIN Lookup	/bin/lookup	This action retrieves card BIN (Bank Identification Number) details based on the provided Transaction ID (TID).
Debt Collection Cancel	/collection/cancel	This action allows merchants to cancel an active dunning process or a debt collection associated with a specific transaction ID.