Invoice and instalment solutions

This page outlines the basics of using invoice and instalment solutions via Netaxept and gives you instructions needed for a fluent implementation.

  • Invoice: The customer receives an invoice after the payment phase and pays the whole sum of the purchase at once by the due date.
  • Instalment: The customer pays the sum of the purchase in parts according to the agreed payment plan. In part payment option, there are often interest and specific fees included in the total sum of the purchase.
  • Account: Type of invoice where purchases are collected and invoiced periodically, for example once per month.

Some payment methods cover both invoice and instalment options. Then, the customer will make the choice whether to pay the purchase at once or in many parts during the payment process in the page hosted by the chosen invoice provider.

 

Use for the end-customer

If the customer decides to pay with an invoice or instalment, they are directed from the merchant’s site to the website of the chosen invoice/instalment service provider. The direction is done either directly or via Netaxept's payment window, depending on the merchant's technical API implementation towards Netaxept. In the service provider's site, the customer is guided through the payment process and after finishing it, the customer will be redirected to the redirectURL specified by the merchant in the Register call, with a proper response code. The invoice provider sends the customer an invoice for the purchase as agreed and settles the payment to the merchant within the agreed time.

 

Activation

To be able to use invoice and instalment solutions in your webshop, you need to sign an agreement with each particular invoice provider you want to use. After the chosen service provider has processed your agreement, they will provide you credentials which you need to enter to Netaxept Admin to activate the payment method in question. You will need to add one agreement for each of the combination of invoice, instalment or account that you want to have, per currency. The merchant is responsible for activating these payment methods in Netaxept Admin and ensuring that all information entered is correct.

  • Log in to Netaxept Admin (test: https://test.epayment.nets.eu/admin or production: https://epayment.nets.eu/admin)
  • Go to "Options" => "Agreement" tab.
  • Choose the correct payment method from the drop down list and click "Add" button.
  • Choose the correct currency and enter credentials. The number of credentials varies between different invoice providers, and the terminology varies as well.
  • Save your changes by clicking "Add" button.

 

Performing API integration

Implement the technical API in accordance with the standard Netaxept's API instructions. Read more about API >

Transaction flow

Start the payment process by sending the information required for the payment to Netaxept by means of the Register call. Compared to the regular card integration, there are some mandatory parameters that need to be sent along the Register call to Netaxept. See below for more information.

After the successful Register call, perform the Terminal call to send the customer either to the Netaxept payment window or directly to the invoice provider's site for the payment. Regarding financial operations done after the Terminal phase, there are some differences depending on which invoice or instalment payment method has been used. Some invoice and instalment payment methods don't support AUTH, CAPTURE, SALE, ANNUL or VERIFY operations, which eliminates a step in the standard payment process done via Netaxept. For example for Klarna, you need to execute either the Process (Auth) and Process (Capture) calls or the Process (Sale) call after the successful Terminal phase. To make sure your setup doesn't try to run not allowed steps, we recommend you to implement the following:

  • Use the "Payment method action list" parameter in the Register call to separate invoice/instalment from card and other payment methods in the checkout phase.
  • Perform the Query call after the Terminal phase to see which payment method was used for the payment, and make the further action based on the payment status.

Mandatory parameters

Goods list

In the Register call, there is a Goods object, under the Order object, which is a mandatory object for all invoice and instalment payment methods implemented via Netaxept. The Goods object contains an array of Item objects, each containing a set of parameters. One Item object represents one product line / item. For each item, Quantity and Amount parameters are required, amount being item price. In addition, either Title or Article number need to be specified. The full set of parameters is listed below. Boolean values are either "true" or "false". For float variables, use the "." character as delimiter, for example: 24 percent VAT is set as 24 or 24.00. Read more about these parameters >

  • ArticleNumber (string) (required if Title is missing and vice versa)
  • Title (string) (required if ArticleNumber is missing)
  • Amount (integer) (required)
  • Quantity (integer) (required)
  • Handling (boolean)
  • Shipping (boolean)
  • IsVatIncluded (boolean)
  • Discount (float)
  • VAT (float)

When working with REST interface, the format of the parameters needs special formatting. As the number of items is variable, you need to send a parameter "numberOfGoods" indicating how many product lines / items should be expected in the Goods list. Then, indexed from 1 up to "numberOfGoods", pass the parameters as amount_N, articleNumber_N etc. where "N" is the serial number of the item. Below you can find an example of this kind of REST call. In Web Services, numberOfGoods parameter is not needed.

Purchase 120 euros that contains two items with the following info:
1. 200 pencils, cost 0,50 euros each, incl. VAT 24%
2. Shipping, cost 20 euros, incl. VAT 0%
3. Payment method "Lindorff" is selected in the merchant's webshop and Netaxept payment window is skipped

The Register call:
https://test.epayment.nets.eu/Netaxept/Register.aspx?merchantId=xxxxxxxx&token=xxxxxxxx&ordernumber=order852&amount=12000&currencycode=EUR&redirectUrl=http://www.test.fi&servicetype=B&language=en_GB&paymentMethodActionList=[{"PaymentMethod":"Lindorff"}]&numberOfGoods=2&amount_1=50&title_1=Pencil&quantity_1=200&articleNumber_1=1&VAT_1=24&IsVatIncluded_1=true&amount_2=2000&title_2=Shipping&quantity_2=1&articleNumber_2=2&VAT_2=0&IsVatIncluded_2=true&customerFirstName=Bill&customerLastName=Buyer&CustomerAddress1=Testadress&customerPostcode=00510&CustomerTown=Helsinki&customerCountry=FI

 

Customer information

Besides the Goods object, in most cases you need to provide contact information of the end-customer for invoice and/or instalment to be an option. The customer's country is mandatory information for most of the invoice and instalment payment methods. It should follow ISO 3166-1 Alpha 2 code, for example: "NO", "SE", "DK", "FI".

There are also some customer information, like customer name, address, post code, town, email address, phone number and/or social security number that are required for some invoice and instalment payment methods. See more information from the table below. Customer information can be of course optionally passed in the Register call to make filling the form in the invoice provider's site easier for the customer. Read more about these parameters >

 

Total sum of items

It should be noted that when accumulating the total sum of each item, it must match the sum specified for the transaction as a whole in the Amount / Order.Amount parameter in the Register call. In the example below, the one pizza (150 NOK) and two carrots (2 * 50 NOK) equals 250 NOK.

Order = new BBS.Order
{
Goods = new BBS.Item[]
{
new BBS.Item {
Amount = "5000",
Quantity = 2,
Title = "Carrots"
}, new BBS.Item {
Amount = "15000",
Quantity = 1,
Title = "Pizza"
}
},
CurrencyCode = "NOK",
Amount = "25000",
OrderNumber = "12345",
}, [...]

 

Support for partial credits and captures

Netaxept supports partial credits for invoices and instalments (AfterPay, Collector, Enterpay, Klarna and Lindorff). When doing partial credit, you need to send the Goods object for that part of the transaction along the Process (Credit) call to Netaxept. The parameter values in the Goods list need to be comparable between the original payment and the credit, i.e. if there have been for example two items in the original Goods list with VAT24% and VAT0%, then the same items and VAT% need to be presented in the credit call too. Item prices may of course vary depending on the amount to be credited. For Klarna, also the Article number parameter is mandatory when doing partial credits. 

Netaxept also supports partial captures for some invoice and instalment payment methods (AfterPay, Collector and Klarna). When running partial capture, the Goods object for that part of the transaction needs to be sent in as part of the capture. Also, if you are running partial capture you later might want to credit, you need to be aware of the SubTransactionId parameter. The SubTransactionId becomes a requirement because when you are doing a partial capture, you are actually creating an invoice, with its own invoice number. The SubTransactionId is available as part of the ProcessResponse, so you get it immediately after running the Process (Capture) or Process (Sale) call. You can also fetch it at any time using the Query call.

When doing full captures or credits, the SubTransactionId and Goods object can be ignored. For the time being crediting invoice and instalment payments manually via Netaxept Admin is not fully supported. It means that in Netaxept Admin you can credit only full amounts but not partial amounts because there is no Goods list available in Credit page.

 

Supported payment methods

Invoice and instalment solutions that are supported by Netaxept at each time are listed below. Also, below you can find information about their main differences. There are slight differences in mandatory parameters (except Goods list which is mandatory for all invoice and instalment payment methods), as well as supported countries and currencies, between different invoice and instalment payment methods.

Name Payment method name in API Supported countries Supported currencies Notes

AfterPay invoice

GothiaInvoice DE, DK, FI, NO, SE DKK, EUR, NOK, SEK

AfterPay instalment

GothiaInstallment DE, DK, FI, NO, SE DKK, EUR, NOK, SEK
  • Customer social security number is required
  • Amount > 400

Collector invoice

Collector FI, NO, SE EUR, NOK, SEK

Collector instalment

CollectorInstallment FI, NO, SE EUR, NOK, SEK
  • Country and Currency matching
  • OrderNumber length <=20
  • ArticleNumber and Title in Goods list
  • Min amount 1000 SEK/NOK and 100 EUR
  • CustomerNotificationMode should be "EMAIL"

Collector account

CollectorAccount

FI, NO, SE

EUR, NOK, SEK  

Handelsbanken invoice

HandelsbankenInvoice      

Handelsbanken instalment

HandelsbankenInstallment      

Klarna invoice

Klarna DK, FI, NO, SE DKK, EUR, NOK, SEK
  • CustomerNotificationMode needs to be set
  • ArticleNumber required for partial credits
  • Requires authorization and capture by merchant
  • More information about Klarna www.klarna.com

Klarna instalment

KlarnaInstallment DK, FI, NO, SE DKK, EUR, NOK, SEK
  • CustomerNotificationMode needs to be set
  • ArticleNumber required for partial credits
  • Requires authorization and capture by merchant

Lindorff invoice and instalment

Lindorff FI EUR
  • Support for DK, NO or SE, please consult Nets
  • Customer address, postal code and city are required
  • Mandatory to generate unique OrderNumber for each transaction to be able to match Netaxept and Lindorff reports. OrderNumber will be shown in the YourReference field in Lindorff's reports
  • More information about Lindoff www.lindorff.com and https://bill.lindorff.fi
  • Read more about Lindorff integration from the Getting Started Guide >

Enterpay B-to-B invoice

Enterpay FI EUR
  • For the time being, only supported in Finland
  • Only Goods object is mandatory, customer information optional
  • Mandatory to generate unique OrderNumber for each transaction
  • More information about Enterpay https://www.enterpay.fi
  • Read more about Enterpay integration from the Getting Started Guide >

 

Getting the invoice 

AfterPay

Getting the invoice from AfterPay is easiest done through Netaxept Admin. Alternatively, the invoice can be pulled directly from AfterPay's API using the SubTransactionId parameter.

Collector

Getting the invoice from Collector is easiest done through Netaxept Admin.

Klarna

After a successful Sale or Capture the invoice will be created and can be downloaded from Klarna at https://online.klarna.com/invoices/[invoiceid].pdf. The invoice ID is available via the Query call, at the InvoiceInformation.InvoiceId parameter. You can also notify Klarna about the way how the invoice is to be sent to the customer by setting the CustomerNotificationMode parameter to "MAIL" or "EMAIL" in the Register call.

Lindorff

After the successful payment, Lindorff will send the invoice to the customer by email. Alternatively, the customer can download the invoice by themselves from Lindorff's online service at https://bill.lindorff.fi

Enterpay

After the successful payment, merchant's chosen settlement partner will send the invoice to the customer in a chosen way.

 

Recurrent billing

Besides the regular invoice and instalment, some invoice and instalment partners support also recurrent billing for billing customers easily on a regular basis. For the time being, Netaxept supports recurrent billing for AfterPay.

In Netaxept, the recurrent billing for AfterPay works in a similar way as regular Easy Payment functionality. Read more about Easy Payment >

Initial transaction

When performing the initial transaction, send the following parameters to Netaxept along the Register call.

  • updateStoredPaymentInfo="true"
  • recurringType=”S”
  • Include “GothiaInvoice” into paymentMethodActionList parameter
  • For invoice to be an option, include Customer country and Goods object in a valid format

After the successful Register call, perform the Terminal call to send the customer to the payment window.

After the customer has successfully passed the Terminal phase, run the Query call on the transaction, to find the token from the parameter panHash, and store this token value on the customer profile for later transactions. In recurrent AfterPay billing, this token value in the panHash field is the same as the Customer ID available in the AfterPay’s system.

Subsequent transactions

When performing the subsequent transaction, the steps follow the ones of the regular card based Easy Payment flow. Send the following parameters to Netaxept along the Register call.

  • panHash=[stored token / customer ID]
  • recurringType=”S”
  • serviceType="C"
  • Include “GothiaInvoice” into paymentMethodActionList parameter
  • For invoice to be an option, include Customer country and Goods object in a valid format

After successful Register call, you can skip the Terminal phase and run the Process(Sale) call to process the transaction.