Integration guide

Consumer invoicing in Finland

Invoices to consumers can be sent through Maventa via email, print, or then as an e-invoices or direct payments to the consumer’s netbank.
For sending invoices to consumers via the email or print route you can force the sending using invoice sending method from either our SOAP or REST APIs.

How consumer e-invoicing to banks works in Finland

Consumer e-invoicing (B2C) in Finland enables suppliers to send e-invoices to consumers’ personal netbanks and direct payments to consumers who do not use an online banking service. This service is only available for Finnish companies registered to Maventa. If you need to send invoices from Finnish company to consumers outside Finland only option is to send them via email or by print.

In Finland B2C e-invoicing to netbank requires activation through bank messaging. Suppliers activate the consumer e-invoicing via Sender info SI-message and by that notify the consumers of the option to receive e-invoices from that supplier. Consumers inform that they want to receive e-invoices from the supplier with Receiver info RI-message. The ReceiverProposal message RP-message is used when the supplier asks for the consumer’s e-invoice address.

Consumer e-invoicing process flow

1. SI-messages are created by and send from the supplier’s ERP to Maventa. Supplier needs to initiate the SI sending process with Maventa separately for each bank they want to use for e-invoicing (see the list of e-invoicing Banks)
2. Maventa sends SI-messages forward to the operator bank
3. Operator bank sends the SI-messages forward to each bank
4. Bank receives the SI-message and stores the information that the supplier is ready to send consumer e-invoices through Maventa. After this the supplier can then be searched from the registry available in the netbank
5. E-invoicing contract is initiated between the supplier and the consumer: consumer informs bank that they want to receive e-invoices from the supplier in question and provides identification reference that the supplier has requested in SI-message (e.g. reference nr)
6. Bank sends RI-message, notification that the consumer wants to receive e-invoices, to the operator bank
7. Operator bank sends RI-message to Maventa
8. Supplier’s ERP downloads Maventa the RI-message and saves the consumer’s information on their end (to consumer registry).
9. The supplier is now set up for sending e-invoices to that consumer through the netbank. See the requirements for consumer e-invoices.

Opening the B2C e-invoicing service

There are currently two types of messages supported by Maventa and needed for opening the service and to setting up the consumer e-invoicing, SI-messages and RI-messages. Prerequirement for using the consumer e-invoicing is to have the bank connection activated for the supplier.

In briefly:

1. Bank network connection activated in Maventa. To check if the connection is open for the SOAP side you can use show_company_configuration and check the bank_send parameter. For REST side use GET /v1/company/profiles to check that the status for BANK network is active.
2. SI-messages successfully sent to each bank
3. Consumer has chosen the company as their biller with RI-message
4. Consumer e-invoices can be sent

   SI-messages

SI-message (Sender info) is a notification to the banking system whereby the supplier notifies banks and informs consumers of its readiness to send consumer e-invoices and direct payments. It could be considered as a consumer e-invoicing agreement between the supplier and the bank.
To make a new agreement SI-message with MessageActionCode ADD is sent through Maventa API to each bank the supplier wants to use for consumer e-invoicing. After sending you can poll the status of the sent messages. For SI messages our system shows OK immediately when the message has been sent OK to the operator bank. Between the banks B2C messages can travel with delay up to 1-4 banking days so keep in mind that possible error messages can arrive even after a week. When all is ok new RI-messages will start to flow in.
If the message fails on the bank side you will get an error. In case SI-message is in error state, you can get the errors by first listing error ids and then viewing the error message.
If there is a need to change or add some information for the agreement it can be done by sending a SI-message with the type CHANGE (e.g. when bank account information is changed or new account needs to be added, or if service provider has changed). Supplier agreement can be deleted by sending SI-message with the type DELETE. This will also delete all the consumer agreements (RI-messages) linked to this supplier agreement.

Implementation guidelines for creating the SI-messages and a tool for creating messages can be found from Finance Finland’s webpage

Note! Since our B2CFI traffic goes through our intermediator bank, Danske Bank, SI-message must have DABAFIHH defined as a sender operator code!

SI-messages (and RP-messages) can also be sent through our user interface (B2C messages -> Sent messages). The messages can be sent separately as one message per file or then all messages in one file. The latter option is something that you will get when creating the messages using FKL’s tool that can be found from the link above.

REST

To send messages (SI, RP): POST /v1/fi_bank_messages
To poll the status of sent message: GET /v1/fi_bank_messages/{id}
To list error message ids: GET /v1/fi_bank_messages/error_messages
To download a specific error message: GET /v1/fi_bank_messages/error_messages/{id}

SOAP

To send messages (SI and RP): message_send
To poll the status of sent message use: message_status
To list error message ids: error_message_list
To download a specific error message: error_message_show

Few tips for the SI-message content

Billing Subject
Consumer billing includes mandatory billing subject code (PaymentInstructionIdentifier) which is an identifier specified by the sender in the SI-message. Billing subject code is used to identify the reason for payment. Same supplier can have multiple SI-messages with different billing subject. When sending consumer e-invoices this same billing subject code needs to be given in the invoice XML. In Finvoice the billing subject is given in the optional EpiPaymentInstructionID field and in TEAPPSXML description, the corresponding element is HEADER / PAYMENT_INSTRUCTION_IDENTIFIER. To get this reason for payment to be visualised for the consumers in their netbank or web payment services you will need to specify it in SellerInvoiceTypeText element and with all language code (FI, SE, EN).

<SellerInvoiceDetails>
   <PaymentInstructionIdentifier>Vuokra</PaymentInstructionIdentifier>
   <SellerInstructionFreeText LanguageCode="FI">Anna viimeisimmän laskun viitenumero </SellerInstructionFreeText>
   <SellerInstructionFreeText LanguageCode="SV">Ge den senaste fakturans referensnummer </SellerInstructionFreeText>
   <SellerInstructionFreeText LanguageCode="EN">Enter the reference number </SellerInstructionFreeText>
   <SellerInvoiceTypeDetails>
     <SellerInvoiceTypeText LanguageCode="FI">Vuokra lasku</SellerInvoiceTypeText>
     <SellerInvoiceIdentifierText LanguageCode="FI" SellerInvoiceIdentifierType="01">Viitenumero</SellerInvoiceIdentifierText>
   </SellerInvoiceTypeDetails>
   <SellerServiceCode>01</SellerServiceCode>
</SellerInvoiceDetails>

Bank account information
Supplier’s bank account information is given in the SellerAccountDetails element in SI-message. Bank account numbers must be in IBAN format and supplier needs to define all the account numbers to be used in the consumer e-invoicing. When sending consumer e-invoices the IBAN given in the invoice must match to at least one IBAN given in the SI-message.

E-invoicing Banks

List of Finnish banks supporting consumer e-invoicing. We recommend to send SI-message to each of these banks:

RI-messages

RI-messages (Receiver info) can be considered as consumer e-invoicing agreements between the consumer and the supplier and they are always linked to the existing SI-message. There will be as many RI-messages as there are consumers using that particular bank and would like to have the e-invoicing with the supplier in question.

RI-messages with MessageActionCode ADD will be sent to the supplier when a new consumer chooses the supplier as their e-invoicer from their netbank. If a consumer’s information is changed, RI-message with the type CHANGE will be sent to the supplier and if a consumer wants to end the consumer agreement with the supplier RI-message with the type DELETE will be sent. It’s recommended to keep your own consumer register on the ERP side that has the updated status for each RI-messages. We recommend to list and download all the new RI-messages daily and then update your consumer register accordingly. If you send an e-invoice and get a sending error that the consumer agreement is not active, poll for the RI messages, there should be the type delete message for that consumer.

REST

To list received RI-messages: GET /v1/fi_bank_messages/ri_messages
To download RI-message: GET /v1/fi_bank_messages/ri_messages/{id}
To delete RI-message (file) from Maventa account (note! Use this only after you have downloaded the messages to your ERP, deletion cannot be undone): DELETE /v1/fi_bank_messages/ri_messages/{id}

SOAP

To list received RI-messages: ri_message_list
To download RI-message: ri_message_show
To delete RI-message from Maventa account (note! Use this only after you have downloaded the messages to your ERP): ri_message_delete

Handy tip for testing: You can also send RI-messages to your own test account using the same method for sending SI-messages. You can both send and download RI-messages yourself to verify that the integration is working before going to production.

RP-messages

RP-message (Receiver Proposal message) is used when the supplier asks for the consumer’s e-invoice address before e-invoices can be sent. When a consumer accepts the proposal, a RI-message is sent to the supplier. RP-message is a way to get more consumers to take the e-invoicing into use.

Use of RP-message requires that

• The supplier and the consumer in question have agreed that the supplier requests the e-invoicing address with an RP message
• Supplier has consumer e-invoicing agreement with the banks (SI-messages are sent and ok)
• The PaymentInstructionIdentifier field has the same data content in the RP as it does in the SI-message

RP-messaging process

1. The supplier sends RP-message with the MessageActionCode value ADD through Maventa with the following information:
   • MessageActionCodeIdentifier value 00.
   • Consumer’s personal identification code is supplied in the BuyerPartyIdentifier field.
   RP-messages can be sent using the same methods than used for sending the SI-messages
2. Maventa sends RP-messages forward to the operator bank
3. Bank displays the RP for approval in the consumer’s netbank. Consumer specifies in the RPFreeText element that the message regards confirmation of the agreed e-invoice subscription.
4. Bank responds with a RI-messages, which contains the consumer’s e-invoicing address. Personal identification code is not returned in the RI-message. RI-message is then forwarded through the operator bank and Maventa to the supplier.
5. Supplier updates the consumer’s information accordingly
6. Supplier sends next invoice as an e-invoice

NOTE! If the Customer has not reacted within 30 calendar days, the Bank deletes the RP-message from the consumer’s netbank. The deletion is not in any way notified with an ack message.

Implementation guidelines for creating the RP-messages and more information for the process can be found from Finance Finland’s webpage

Requirements for consumer e-invoices or direct payments

• Billing subject code is mandatory information on the consumer e-invoices (Finvoice - EpiPaymentInstructionID and TEAPPSXML - HEADER / PAYMENT_INSTRUCTION_IDENTIFIER). This is the element that tells that the invoice in question is indeed for consumer.
• Invoice type codes used:
  • Finvoice: Element is InvoiceTypeCode. Use INV01 for consumer’s e-invoices and INV09 for direct debits.
  • TeappsXML: Element is HEADER/INVOICE_TYPE. Use 00 for consumer’s e-invoice and 08 for direct debits.
• Consumer e-invoice doesn’t have business ID (Business Identity Code = Y-tunnus in Finnish)
• When sending consumer e-invoice it is mandatory to use the same supplier’s account information (IBAN/IBANs) that was given in the SI-message otherwise the sending will fail on bank’s side.
• Make sure there is enough time for the consumer to pay the invoice. There should be at least 3 days to the due date from the time of sending the invoice
• Remember to handle the possible notifications of the direct payments. Most of our integrators that send a lot of direct payments send notifications through our Mass printing service as a letters. Either they send one notification for one cunsumer that lists all the upcoming direct payments for the current year or then one notification each month.

Closing the B2C e-invoicing service

Consumer e-invoicing can be deactivated by sending SI-messages with the type DELETE. This will delete the supplier agreements with the banks and remove the supplier from the list of companies providing consumer e-invoicing from the netbanks. Deactivation and deleting of SI-messages will also delete all the consumer agreements (RI-messages) linked to the supplier agreement in question. In case there is only a need to change the service provider or other information on the SI-messages there is no need to delete the existing agreements but instead the information can be changed easily by sending SI-messages with the type CHANGE.

Changing service provider

In case the service provider will be changed you will need to send SI-messages with the type CHANGE from the old service provider and with those SI-messages inform which will be the new service provider. In this way all the existing consumer agreements (RI-messages) will follow along to the new service provider and there is no changes needed to be done by the consumers. Note! It might take few banking days for the SI messages to travel to each bank and to get validated so you should be prepared for the possible errors to arrive few days after the sending of the messages. This means that you should not close down the old connection immidiately but instead you should wait for couple of days (5 days should be enough). Only after those few days if no errors arrive you can close the old connection. Note! RI-message files from the old service provider are not moved to the new service provider in any automated way. You will need to make sure you have downloaded the files or saved the information to your end.

InvoiceSenderAddress and InvoiceSenderIntermediatorAddress should have the current sender information and with NewInvoiceSenderAddress and NewInvoiceSenderIntermediatorAddress you can inform the new sender information:

<InvoiceSenderInformationDetails>
<InvoiceSenderAddress>003712345678</InvoiceSenderAddress>
<InvoiceSenderIntermediatorAddress>DABAFIHH</InvoiceSenderIntermediatorAddress>
<NewInvoiceSenderAddress>003787654321</NewInvoiceSenderAddress>
<NewInvoiceSenderIntermediatorAddress>NDEAFIHH</NewInvoiceSenderIntermediatorAddress>
</InvoiceSenderInformationDetails>

Consumer invoicing in Norway (B2CNO)

Invoices can be sent through AutoInvoice consumers via direct debit (avtaleguiro), eFaktura, Vipps, DPI, e-mail and print. The invoice can be specificed to go a specific route like efaktura or it can be specified to try all routes in a predefined order.

Agreements

In order to send invoices to consumer the main vendor agreements needs to be signed. The agreement capture, and the direct debit service cant be activated at the same time or after the vendor agreement is active.

Business to Consumer vendor agreement

Before you can send any invoices B2C through AutoInvoice, or enable any of the extra features, the main Vendor agreement must be activated. Only a norweigian company account in AutoInvoice can send invoices to consumers and be able to activate the business to consumer vendor agreement.

Note that when the agreement is activated the supplier gives consent for visma to delete any old agreement they might to currently send eFaktura, and fetch all their existing consumer agreements.

This can be done either through the API or UI. API method:

Agreement capture

Note! This feature will be depricated by Nets december 1st 2021.

Agreement capture (Avtalefangst) is a bank feature where the consumer gets a suggestion to enter into an e-invoice agreement with the vendor, when paying the paper invoice in the nettbank. By using this feature the vendor will reach a high number of consumer e-invoice agreements in the fastest way possible. This is an easy, fast, and user friendly way to enter into a consumer - vendor agreement. The consumer does not need to know their e-invoice reference since that is reported in the KID number. This feature is dependent on the issuer having an OCR agreement with their bank.

How it works:

When the issuer of the invoice reports in their KID, bank account number, and the e-invoice reference position in the KID to Nets through AutoInvoice, then Nets creates an agreement capture rule in the bank. This works so that when the consumer gets the paper invoice and punches in the data manually in the online bank, the bank recognizes the bank account and the KID and identifies that there is an agreement capture in place. When this happens the consumer will get a questions like “This supplier can send you e-invoice in the future. Would you like to accept?”. When the consumer accepts then the bank creates the consumer e-invoice agreement based on the e-invoice reference that has previously been reported and is located in the KID number. That information is then fetched by AutoInvoice and is entered into the CV registry and the next invoice will be sent directly to the netbank as an eFaktura.

This can be enabled through the API or the UI API method:

Direct debit agreement for AvtaleGiro

Note! In pilot mode

Through AutoInvoice it is possible to send an invoice and AutoInvoice will route it is a direct debit invoice to Nets if there is an agreement active, and there is an active consumer mandate. The supplier does not need to create a deduction file, that is done based on the invoice at Nets.

To get started the supplier needs a direct debit agreement (avtalegiro) with their bank. This is a manual process today that is handled outside of Visma. In the agreement with the bank the supplier must specify customer ID = 229221. This is to identify the direct debit feature with visma.

If the supplier already have an active agreement with their bank they can activate direct debit through AutoInvoice and we configure the agreement with Nets.

AutoInvoice needs the following information from the company:

1. Bankaccountnumber that the ATG agreement is registered on.
2. Length of KID (numbers of digits in KID including control digit)
3. Mandate/Reference position in KID (example 1-6)

Note! If the supplier already has an active agreement and are already sending deduction files through another route, activation in AutoInvoice does not stop the old route like it does for eFaktura to netbank. Meaning they can send invoice combo through us and deduction file through old channel and it will not be stopped at Nets. However, the mandates can only be fetched from Nets by Visma.

Agreement can be activated through the API or UI. API method:

Different invoice routes

Sending an invoice as direct debit (AvtaleGiro)

Note! In pilot mode. Requires a seperat activation which can be done by contacting AutoInvoice team.

Instead of the supplier creats a deduction file and sends to Nets, or through another channel like AutoPay, the supplier can instead send the invoice via AutoInvoice and the deduction file is created based on that invoice. The notification (eFaktura, e-mail or print) is also handled and sent out by AutoInvoice. Meaning the supplier does not have to relate to two different channels. Mandates will be collected and stored in AutoInvoice.

Prerequisites

1. Supplier must have active direct debit (avtalegiro) agreement with their bank.
2. Supplier must have active eFaktura agreement with Visma (AutoInvoice).
3. Supplier must activate direct debit through AutoInvoice.
4. Consumer must have active direct debit agreement with supplier (mandate).

Notification on upcoming Direct Debit

Its the consumers choice if they want to be notified on an upcoming direct debit and they make that choice when they en they enter into an atg agreement with their supplier. Its either a yes or no to notification, not a how. As a priority the notification will always go as efaktura if they have that activated, if not it can go as e-mail or print. IF the consumer does not want to be notified AutoInvoice only sends the invoice as a direct debit with no notification.

Notification via eFaktura

If the consumer has efaktura activated, either through Y2A or with a direct agreement with the supplier, the notification will always be sent to netbank. It will be shown as an invoice with a direct debit and will not be possible for the consumer to pay.

Notification via e-mail

If the consumer wants to be notified, and does not have eFaktura, then the notification will be sent as e-mail as long as there is an address available. The text in the e-mail specifies that this is a direct debit agreement to eliminate the risk of it getting payed twice.

Notification via print

If the consumer wants to be notified, and does not have eFaktura or any e-mail address, then the notification will be sent to print. AutoInvoice will add a coversheet to the invoice where it specifies that this is a direct debit and should not be payed.

If there is no active mandate the invoice will be routed to the next specified route.

Sending an invoice as eFaktura to Nets

When the vendor agreement is active the first invoice can be sent. If the supplier has moved over from an other solution, the existing efaktura consumer agreements will be fetched to Autoinvoice when the vendor agreement is active. In order to send an invoice as eFaktura the receiver must have a consumer agreement directly with the supplier, or be registered in the “Yes to all” registry with Nets (JTTA).

Consumer vendor registry:

Note! Unique consumer agreements with one supplier will be depricated December 1st 2021 and to be replaced enteirly with JTTA registry.

The consumer vendor registry stores all the consumer agreements, or the consumer eFaktura reference in various states. A consumer’s eFaktura reference is what identifies the consumer with the vendor, and it works as a connection between the consumer and their invoices. It is the central role in transporting B2C invoices between the vendor and the consumer as eFaktura.

• It is highly recommended that the e-invoice reference is the same as the customer number in the ERP. Therefore it is not possible to reuse customer numbers when sending B2CNO invoices.
• It is highly recommended that the e-invoice reference is included in the KID number as this is mandatory for agreement capture.
• If no e-invoice reference is specified AutoInvoice creates the e-invoice reference based on customer number.
• It is illegal to send an e-invoice reference based on social security number.
• The e-invoice reference must be minimum two numbers and always numeric.

There are 4 scenarios where consumer agreements are added into the CV-Registry:

1. When a customer activates the B2CNO vendor agreement in AutoInvoice the existing agreement that they might have will be automatically deactivated and all of their existing consumer agreements that are active will be copied from Nets and enteres into the customers CV-Registry.

2. AutoInvoice sends out a consumer request requesting the consumer to activate an e-invoice agreement with this vendor. Consumer does this by following the link in the e-mail/SMS and accepting through BankID. Agreement then gets copied from Nets to AutoInvoice CV-Registry.

3. Agreement capture with OCR (Avtalefangst med OCR). If agreement capture is active, its a seperat activation, then when consumer pays an invoice in the nettbank it will trigger a question to the consumer if they want to receive an eFaktura next time. This consumer agreements is then fetched and seen in the suppliers consumer - vendor registry.

4. When the supplier enters into the B2CNO vendor agreement with AutoInvoice, they will automatically be searchable in all netbanks. A consumer can then search for the vendor in their nettbank, and activate their e-invoice agreement automatically.

   • Consumer must know their e-invoice ref. This is written on the cover sheet on their printed invoices.
   • The e-invoice reference will automatically be entered into the customer number field in the AutoInvoice registry

When the vendor sends an invoice to a consumer with an existing e-invoice agreement the invoice will be directly transported to Nets and then to the consumers netbank. Note the following:

• If the existing e-invoice reference is not based on the customer number, the e-invoice reference must be specified on the invoice - in the e-invoice address field. If not, AutoInvoice will treat the this as a new agreement and send out a consumer request.
• If the existing agreement is based on customer number, the e-invoice reference does not have to be specified. Autoinvoice will match the customer number in the xml to the customer number/e-invoice reference in the CVR and send directly to the nettbank.

API methods:

Yes to all:

Yes to all, or Ja takk til Alle (JTTA), is used to send an eFaktura to Nets if there is no active consumer agreement in place. Instead of an efaktura reference, the consumer is identified using a eFaktura identifier. With an e-invoice reference there is a direct connection between the vendor and the consumer, but an e-invoice identifier is more general that all vendors can use to send an e-invoice to that consumer. The consumer activates this by logging into their nettbank and activates yes to all, meaning that the consumer accepts e-invoices from all vendors that are able to send e-invoice. If this is activated then there is no need for the supplier to send out any consumer requests and the first invoice can be sent directly to the consumers nettbank.

Note! AutoInvoice does a check towards Consumer Vendor Registry (CVR) before doing a lookup towards Y2A. If there is an active agreement in CVR then there will be no lookup towards Y2A.

When the consumer activates Y2A in their netbank the banks pushes certain information to Nets Y2A registry that Autoinvoice uses for lookup to get the consumers e-invoice identifier. Today it is mandatory for all banks to push Social Security Number (SSN) to the registry but other aliasas include e-mail, phone, address, postal code, first name, and last name. On the basis of these AutoInvoice does a look up towards the registry. If there is a hit then we forward the invoice directly to the netbank.

AutoInvoice does a lookup with the following information (Note that these can change):

1. SSN
2. Telephone and e-mail
3. If phone or e-mail is missing then name, postalcode and city is added.
4. If there is no phone or e-mail then there will be no lookup towards Y2A.

If AutoInvoice cannot find an active eFaktura reference, or a eFaktura identifier, the invoice will be routed to the next route.

Send an invoice as eFaktura to Vipps

AutoInvoice will check towards Vipps based on mobile number and get back a token if the consumer has activated Y2A either in their netbank or in their vipps application. If the consumer has not activated Y2A the invoice will not be sent to vipps.

Requirements on consumer to receive an invoice in Vipps:

1. Consumer has activated Vipps eFaktura in Vipps application.
2. Consumer has enabled Y2A in their nettbank or in their vipps application.

The invoice will then be sent directly to Vipps and because of the merge between Nets and Vipps eFaktura, the invoice will also be visible in the nettbank. Invoice can be payed in either and status updates in both. The same is true the other way around, if the invoice is sent to nettbank, the invoice will also be shown in Vipps.

However the following scenarios need to be taken into account:

1. There needs to be a valid payment source. The consumer needs to add their bank account number in vipps that is towards a bank that supports Vipps payment for eFaktura. If this is not true, the invoice will only be shown in the nettbank even when the invoice is sent to Vipps.
2. If the consumer does not want to show the invoice in vipps, there is a toggle for this in vipps, the invoice will still be sent to vipps but visible only in netbank.
3. There is no scenario anymore where the invoice is only shown in vipps.
4. If the invoice is sent to nets, the invoice will also be shown in Vipps if above is true.

KID number: Supplier does not have to send KID when sending invoices to Vipps. If the sender does not have OCR agreement with their bank, and does send KID number then the payment will not go through.

Fallback settings: There is no fallback setting to sending to Vipps. Instead when using the operator code B2C_VIPPS and B2CNO the invoice automatically gets sent to fallback e-mail and print through route_order if the recipient has not activated Vipps eFaktura.

Creditnotes: Not supported. Invoices can be sent to Vipps and invoices with total amount = 0.

Direct debit invoices: Direct debit invoices, or avtalegiro + efaktura combination invoices, are not supported through Vipps.

Attachments and invoice image: Attachments are supported through visma document hotel. Limitations are the same as to print. AutoInvoice send a link to Visma document hotel where we show only PDFs. If the invoice contains other formats like .png we do not pass these on to consumer.

Status:

When sending an invoice to Vipps the invoice is then validated and been sent to the consumers application and is visible under the payment section in the application. This is done in about 15 minutes. Status with Vipps is then pending and status with AutoInvoice is sent. Sent status is the final status of this invoice. There it will stay until 14 days after due date then it is removed from the application.

There is no way to know if the consumers has payed the invoice. Vipps does not collect the information from the banks.

Explanations of the states in Vipps: https://github.com/vippsas/vipps-invoice-api/blob/master/vipps-invoice-api.md#detailed-information-about-invoice-states-and-transitions

Note: ERPs that use invoice_create method can not send invoices to VIPPS because the phone number could not be saved to Database

Send an invoice to Digital Postkasse Innbygger (DPI)

AutoInvoice can route an invoice to DPI, which is used only by municipalities (Enterprise). When sending to DPI the payload must contain a social security number (personnummer) in a .aix file. The SSN will be used to check the consumer against the Kontakt og Reservasjonsregistret (KRR). In KRR the consumer has choosed if they want to receive invoices or not to their DPI account, and if that account is in either eBoks och DigiPost.

In order to send to DPI or send with SSN contact partner support or AutoInvoice team.

If all is OK the invoice will be routed to DPI..

Sending to Nets

…

Peppol eases the trade between suppliers and buyers by providing a standardised way for exchanging trading documents electronically within countries and cross-border. Sending and receiving between recipients takes place over Peppol Access Points that connect the buyers and suppliers to the network.

Maventa is one of the cerfified Peppol Access Points. This means that when you are integrated to Maventa you can easily provide connection to Peppol to your customers.

Invoice sending in Peppol

• Sending in Peppol network doesn’t require registration, Maventa customers can send invoices to Peppol network in the same way as to any other operator
• To send the invoice, sender gives the recipient’s Peppol address and sets PEPPOL as the operator information.
  • Peppol address is the recipient’s electronic invoice address in the Peppol network. It consists of an identifier prefix and company identification number
    • Identifier prefix is a code that tells what the type of the identifier is in question
    • Company identification number is the identifier of the company e.g. organisation number
  • Identifiers used are depending on country, see https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/ for more information
    • For example in Norway, Peppol address is formed based on organisation number, prefix used for Norwegian organisation number is 0192. For Norwegian company whose organisation number would be 123456789 Peppol address would be 0192:123456789
• To look up Peppol recipients (to see if a company can receive invoices in the Peppol network) you can use Maventa Finder
• Invoices are sent over network in Peppol formats. If the original invoice is not in Peppol format, it will be converted before the send by Maventa.
• Invoices going to Peppol are validated against the format validation rules, invoices that are not valid cannot be sent in Peppol network.
  • See more information about Peppol formats at https://peppol.eu/what-is-peppol/peppol-profiles-specifications/

Invoice receiving in Peppol

• To receive invoices in Peppol, company needs to be registered as Peppol receiver
• Registration is free of charge and invoice receiving is billed according to the used price scheme for e-invoices
• After registration company can receive electronic invoices from all companies that have capabilities to send over Peppol network
• When registering to Peppol company chooses what kind of documents to receive
• The available profiles to register are dependent on country
  • All companies registered to receive invoices will register the common Peppol BIS formats that can be used in all countries. Some countries have country specific formats that will be registered at the same time.
• When company is registered their information is added to Peppol Directory. Peppol Directory is the common address book that lists all network receivers and their receiving capabilities. By looking at the Peppol Directory you can find all the document types and versions a specific company is registered to receive.

Register company as Peppol receiver

APIs to use
REST API - Invoices and other documents
SOAP API - Enable/disable, invoices only

• After company account is registered to Maventa you can register the company as Peppol receiver
• When you call the API, Maventa makes the registration to Peppol SMP (Service Metadata Provider) that is then synced to common Peppol address book Peppol Directory

Note that using different Access Points for different document types is possible, e.g. one to receive invoices, another to receive orders, but company cannot register the same document type to different Access Points.

If the company is already registerd to receive invoices through another Access Point than Maventa this registration needs to be removed by the old Access Point before Maventa can do the registration

Create registration

To create registration to Peppol

REST API Call POST /v1​/company​/profiles

• Required information
  • Supported company profiles
    • for invoices and credit notes: INVOICE_AND_CREDIT_NOTE
  • Network: PEPPOL
• After registration is ready you will be returned the identifier/Peppol address that company was registered with

{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "profile_version": null,
  "endpoint_id": "003712345678",
  "scheme": "0037",
  "network": "PEPPOL"
}

SOAP API Call enable_operator with enabled=true

• This will create the registration automatically for profile INVOICE_AND_CREDIT_NOTE
• The method returns OK if the registration was successful. Note that the identifier/Peppol address is not returned for this method

Supported countries and identifiers used in registration

Maventa creates the registration with the following identifiers (schemes)

• Norway - Organisation number (prefix 0192)
• Finland - OVT (prefix 0037)
• Sweden - Organisation number (prefix 0007)
• Denmark - CVR (prefix 9902)
• Netherlands - KVK or VAT number (prefix 0106 or 9944 - depending which is used to register company account to Maventa)

If you want to register a participant outside of these countries or with a different identifier please contact Maventa.

Get information of existing registrations in Maventa

REST API

• To fetch information of Peppol registrations use method GET /v1​/company​/profiles
• To fetch more information of a specific registration use method GET/v1/company/profiles/{id}

Monitor registrations

REST API

To follow up when the registration has been succesfully completed you can register to callback notifications. Use the event type NETWORKS to get notification of all changes in the registration statuses.

Delete registration

To remove registration from Peppol network

REST API

• Call DELETE /v1​/company​/profiles and give the profile id for the registration you want to delete

SOAP API

• Call enable_operator with enabled=false
• This will delete the registration for the profile INVOICE_AND_CREDIT_NOTE

Recommended routine and notes

• Company email needs to be set on Maventa account to make the registration (min. in Norway)
• Registrations happen usually straight away, but if there are issues with the Peppol register there can be a delay of couple of days before the actual registration happens
• Before creating the registration is good practise to check the existing registrations for the company
  • if company is already registered you are good to go
  • if not, if there are any old inactive registrations e.g. failed ones delete them and then create a new registration
• If company is already registered to receive invoices but to another Access Point than Maventa the registration will fail and user needs to contact their old Access Point to deregister the company before the registration in Maventa can take place
  • When the API call fails show error message with instructions to user
  • When the old Access Point has removed their company registration from Peppol, delete the failed registration attempt from Maventa and register the company again

Print can be used as the option to deliver the invoice if it is not possible to send it by e-invoicing or email.

The requirements to send the invoice by print are that:

• the sender company needs to have the print service activated
• the postal address of the recipient needs to be found on the invoice
• see more information from invoice sending guide on how invoices are routed to print

See the used price list for print related transaction costs.

Opening the service

To activate the print service call API method configure_company and set parameter print_and_send_request = 1 (1 = yes, 0 = no). Show_company_configuration method and parameter print_and_send_enabled (true/false) can be used to check the status of the print service.
Note! For Finnish and Swedish companies (without VAT number) activation will take some time since requests are confirmed manually. Bear this in mind especially if activating the service takes place outside regular business hours.

Printing of attachments is by default enabled for Norwegian and Dutch companies, where as it is by default disabled for Finnish companies. To enable or disable the printing of attachments, use configure_company and set parameter print_attachments (true = enable, false = disable).

Template

Invoices sent via print service will by default use the Maventa PDF-template. This template is optimized for effective handling. If you wish to use your own company logo on the PDF-invoice, you can upload it with update_logo API method. Note that PNG with transparency is not supported. To remove the uploaded logo use remove_logo method.

If you wish to use your own PDF-template, in configure_company method set parameter print_and_send_own_pdf = true. This will add a coversheet with address information to all printed letters, which means there will always be at least two pages. It is possible to exclude the coversheet if you make sure that the address details fit into envelope window. Contact support to confirm your layout. Printing service uses C5 envelopes.

Examples of Maventa templates here.

Note that when using your own template you should be careful and take technical restrictions in consideration.

Closing and reopening the service

To close the print service, call configure_company method with parameter print_and_send_request = 0.
To reopen the service, just follow the steps in chapter Opening service. The print service is enabled immediately after activation, without approval needed.

Implementation over user interface

Print service activation, closing and configuring the settings can all be done over the Maventa UI. The print service settings can be found under Invoice sending settings.

Maventa Mass printing service (also known as Payslip) is a service that enables sending of EPL and PDF files as letters through the printing service in Finland. Service was initially build to send payslip material, but it can be used for sending any kind of letters, as long as the printing service rules are followed.

Payslip can be used either through the UI from address https://payslip.maventa.com (testing https://payslip-stage.maventa.com) or via HTTP API.

User account opening

You need a separate user account for the Mass printing API in order to use it. You can open the account with an API call to https://payslip.maventa.com/register using existing vendor_api_key and company_uuid for Maventa.

Request for registering

Response for registering

The response code will always be a HTTP 200 and the response body is one of the following:

Sending

To send a letter to Mass printing service call the API endpoint payslip.maventa.com/input_public.

Headers for sending

You need to give authentication using HTTP headers. You can give either:

• USERNAME and USERPW with which you registered your Mass printing API account
• COMPANY-UUID and USER-API-KEY of your Maventa account

POST parameters for sending

Response for sending

The response code will be a HTTP 200 and the response body is one of the following or “401 Unauthorized” if authentication fails:

Zip file content

PDFs

• One zip file can contain multiple PDF files but only one letter per PDF file. One letter can have multiple pages.
• Each PDF must be accompanied with iPost-XML metadata file (iPost LetterBundle format version 0.4). Note! information given in IPost-XML overrides the API parameters. You can download a zip file containing iPost-XML v0.4 implementation guidelines here
• Page count on the iPost-XML (pages element) must match to the actual page count of the PDF
• We prefer that one zip file contains only one letter (one PDF file) + iPost-XML metadata file
• Always use unique hash for each zip file. zipHash and hash values can be the same since one ZIP file can contain multiple PDF files
• Zip file max size is 1 GB

Envelope size

Finnish printing service uses two different envelope sizes. Smaller C5 envelope is used when there are up to 8 sheets in the printed document. When document has more than 8 sheets a bigger, more expensive, C4 size envelope is used. There are different billing actions for these two cases. In case documents are printed as duplex (double-sided) there needs to be more than 16 pages on an document for it to be more than 8 sheets and to end up in the C4 envelope.

<?xml version="1.0" encoding="ISO-8859-1"?>
<lb:LetterBundle schemaVersion="v0x4" senderFileId="FileD1" xmlns:lb="urn:itella-letterbundle-v0x4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:itella-letterbundle-v0x4 LetterBundle_V0x4.xsd">
  <lb:Bundle senderBundleId="">
    <lb:BundleCommon creationDate="2020-06-24T13:17:00.0Z" isTest="false">
      <lb:Sender companyName="Maventa Oy" contact="" contactPerson="Maventa Support" email="support@maventa.com" phoneNumber="010-5058474" ovtID="003721291126">
        <lb:SenderAddress>
          <lb:Eu1 name="Your company Oy" address="PL 000" postalCode="00101" city="Helsinki" countryCode="FI"/>
        </lb:SenderAddress>
      </lb:Sender>
      <lb:StdBundleProcessing customerId="" departmentClassification="false" electronicArchiving="T" envelope="S" fileFormat="0" isDuplex="true" letterClass="2" paper="0" password="" serviceFunction="0"/>
      <lb:ExternalFile fileName="sent_filename.pdf" format="PDF" senderFileId="wm_0c5c09e0-03d3-4340-bb6b-0c3c14be7f42">
        <lb:CheckSum type="MD5" value="nnnnnnnnnnnnn"/>
      </lb:ExternalFile>
    </lb:BundleCommon>
    <lb:Letter senderLetterId="LetterID1">
      <lb:LetterMeta>
        <lb:Location pages="1" startPage="1"/>
        <lb:Recipient>
          <lb:Address>
            <lb:Eu1 address="Kotikatu 1" city="Helsinki" countryCode="FI" name="Asiakas Anssi" postalCode="01001"/>
          </lb:Address>
        </lb:Recipient>
      </lb:LetterMeta>
    </lb:Letter>
  </lb:Bundle>
</lb:LetterBundle>

EPLs

• One EPL file per send (one EPL file can contain multiple letters)
• Before sending EPL format contact Maventa support to verify that your EPL form is supported.

Instructions for letter layout

Latest instructions for the letter layout

Receiver information should be marked as clearly as possible with the following order to make sure machine readability:

Checking the status of sent packages

To check the status of the sent package, use https://payslip.maventa.com/file_status. API call contains HTTP-header where user name and password are given with USERNAME and USERPW parameters. In addition a GET for giving the sent file name with filename parameter.

Headers for checking the file status

You need to give authentication using HTTP headers. You can give either:

• USERNAME and USERPW with which you registered your Mass printing API account
• COMPANY-UUID and USER-API-KEY of your Maventa account

GET parameter for checking the file status

Response for checking the file status

Delivery schedule

PDF material that has been sent to Maventa before 24:00 will get printed during the same night and sent to post office next morning. Post will deliver material to the receivers according to the chosen letter class.

User account closing

If you wish to close the service please contact Maventa support.

How Receivables Management service works

The Receivables Management service handles payment monitoring, payment allocation, sending of reminders, and debt collection on behalf of the company. Company only needs to create and send the invoice as normally (including the error handling) and the service does the rest. The service is provided by Visma Financial Solutions Oy through Maventa and it is included in the Maventa service with no additional costs for using it. Only costs there might be are related to the debt collection process in later phases and if assignments are cancelled (see price list).

New things in planning

• Customer specific prohibition of collection (through the UI and API)
• Possibility to use own invoice image if some prerequirements towards the EPR is fulfilled (ERP needs to be able to modify the XML)
• Timed activation. Possibility to decide what will be date the service gets activated and invoices start to flow through the service
• API to modify Receivables settings (contact person information etc.)

Receivables Management process flow

Step by step process flow

1. Activation of the service. When the service is activated all the invoices are routed through the Receivables Management service (with few exceptions).
2. Invoices are sent from the ERP to Maventa as normal. Make sure the invoice xml is valid and according to the requirements. Invoice image is dropped. Note! Sender is responsible for making sure the invoice reaches the receiver! If the invoice ends up in the error state it is sender’s responsibility to reroute the invoice or handle the error case in some way.
3. Maventa gives the invoice content to Visma Financial Solutions for modifications (What information is changed and why).
4. Modified invoice and new invoice image (and attachments from the original invoice) are then sent to the receiver through the normal Maventa sending process. Sender is still responsible for handling invoice sending related errors and for making sure invoice reaches the receiver. At this point a receivables assignment is created. This assignment can be used to follow up the process on the Visma Financial Solutions side.
5. Receiver pays the invoice with Visma Financial Solutions’ payment information and Visma Financial Solutions pays the money to the sender account. When invoice gets fully or partially paid Visma Financial Solutions will create an event for the assignment about that payment. These events tells what has happened to the assignment.
6. If receiver doesn’t pay the invoice on time, Visma Financial Solutions handles reminder sending according to their process schedule and later on handles the possible debt collection. All this you can follow up through the assignment events.

Exceptions on invoices routed through the service

1. Only invoices with currency EUR are accepted. Invoices in other currency will skip the service and will be sent out directly to the receivers without Visma Financial Solutions being responsible for monitoring them.
2. Service does not support the following invoice XMLs: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL, Facturae.
3. Consumer e-invoices to netbanks are not routed immediately through the service after the activation. There will be a 5 days delay during which all the consumer e-invoices will go directly to the banks instead of going through the Receivables management. This delay should give the company enough time to update their consumer agreements (SI-messages) with banks. After the delay the consumer e-invoices are also routed through the Receivables management like all the other invoices. See more from How to handle Finnish consumer invoicing

Invoice content requirements and error handling

• Full receiver’s address information is given
  If there is something wrong in the address your invoice will end up in the error state with the following error message SEND ERROR (REASON: RECEIVABLES-SERVICE: Postal code for CITY_NAME xxxxxx not found (code #5)) and won’t get sent out to the receiver. You will need to create a new invoice with corrected address and send it again.
• Due date is not in the past and there is at least 3 days until the due date
  If due that has passed or there it is within 3 days your invoice will end up in the error state with following error message SEND ERROR (REASON: RECEIVABLES-SERVICE: The due date for the invoice is within three (3) days or has already passed (code #13)) and won’t get sent out to the receiver. You will need to create a new invoice with proper due date and send it again.
• Duplicate invoice numbers are not allowed to be used
  Same invoice number cannot be used twice. All sent invoices must have unique invoice number. If you try to send an invoice with the same number you have previously sent to the service the sending will fail with the error message (SEND ERROR (REASON: RECEIVABLES-SERVICE: Invoice already exists (code #6 e5006e70-dfab-49da-90fd-2e47d2eb8ea6))) and won’t get sent out to the receiver. It is highly recommended to prevent the use of same invoice number already when user tries to create an invoice in the ERP. This to avoid unnecessary error handling on Maventa side.
• Sum of lines must equal the total sum of the invoice

In all of the above cases the invoice IS NOT SENT to the receivables service which means that it won’t be sent to the receiver either. Below is explained how to handle the error cases when the invoice IS ALREADY SENT through the receivables service when the invoice ends up in the error state:

Invoice is sent through the receivables service just before it is sent forward from the Maventa to the receiving operator/access point. In case the receiving operator returns an error (which can happen even a week after the sent) sender needs to handle the failure somehow. Sender is responsible for getting the invoice delivered to the receiver:

• In case the invoice ends up in the error state because of the wrong e-invoice address (for example the receiver doesn’t anymore receive invoices to the e-invoice address that the sender has defined as the address) sender needs to reroute the invoice to a new address. Rerouting can be done either from the user interface under the invoice details or then via API from the ERP. Using rerouting functionality does not create a new assignment.

• If the reason for failure is in the XML content, the sender needs to send a new invoice with corrected information. In order to do so the sender probably needs to credit the existing erroneous invoice in the ERP. Addition to crediting the invoice in the ERP the sender needs to communicate that to the receivables assignment in question so that Visma Financial Solutions also gets notified to close the assignment. This can be done using the credit_note event. We highly advise to automate this process in the ERP side to always create a credit_note event to an assignment when the user creates credit notes in the ERP. Although marking the assignment as credited can also be done through the user interface. Note! When sending the new corrected invoice, remember to use a new invoice number to avoid the duplicate invoice number error above.

When the invoice ends up in the error state, Visma Financial Solutions will get notified about it and they will set the assignment in question to the temporary prohibition of collection state until the error is handled by the sender. If the sender doesn’t do any actions within 1-2 weeks, Visma Financial Solutions will send an email notification to the sender asking how to proceed. If they don’t get any answer to that email within 2 weeks, they will close the assignment in question.

What information on the invoice gets changed

• IBAN - Visma Financial Solutions will replace the payment information from the sent invoice with their own IBAN. In this way the receiver pays the invoice using Visma Financial Solutions account information and then Visma Financial Solutions pays the money to the sender using the account information that was given in the service activation form, and the reference number from the original invoice created by the sender. On the invoices there will only be one IBAN and that IBAN will be the same for all the invoices sent from the company. You will get the IBAN as a response from the activation API call.
• REFERENCE NUMBER - Visma Financial Solutions will replace the reference number from the sent invoice with their own one. You will get the reference number used by Visma Financial Solutions from the assignment.
• FACTORING CLAUSE is added
• InvoiceFreeText Visma Financial Solutions will add new InvoiceFreeText elements to the invoice containing a link to their customer service for the receiver: VERKKOPALVELU: https://www.laskuhelposti.fi/ KIRJAUTUMISTUNNUS: xxxx. Existing InvoiceFreeText elements won’t get overridden but new ones will be added.
• Elements in Finvoice XML that gets modified: SellerAccountDetails, EpiBfiIdentifier, EpiBeneficiaryPartyDetails, EpiReference, EpiRemittanceInfoIdentifier, VirtualBankBarcode, FactoringAgreementIdentifier, FactoringFreeText and InvoiceFreeText
• INVOICE IMAGE - Maventa will create a new invoice image from the modified invoice XML so that the receiver gets the correct information also on the image.

Reminder and debt collection schedule

In case the receiver doesn’t pay the invoice on time, Visma Financial Solutions will first sent out reminder invoice. First reminder is sent 10 days after the due date of the invoice for B2B invoices, and 14 days after due date for consumer invoices (B2C). Reminders are always sent through the normal post (Letters won’t be sent during weekends or public holidays which will then in some cases add few additional days to the schedule).

Opening the Receivables Management service

To open the Receivables Management service use REST API method PUT /v1/services/receivables to initiate the activation process. In order to get the service activated an electronic agreement between the company and Visma Financial Solutions needs to be filled and signed by a person having authorized signatory rights for the company (or the one signing needs to have a letter of attorney which needs to be attached to the agreement). Signing of the electronic document requires authorized person to authenticate themselves using their personal online bank identifiers or mobile signature. Authentication and signing process is done by our partner VismaSign. With the parameter authorization_email you can specify the email address for which the VismaSign request is sent to.

When agreement is signed and verified the service gets activated. Note! If you have consumer invoicing enabled you will need to add Visma Financial Solution’s provided IBAN to your sender agreements (SI-messages). You will get the IBAN as a response parameter from the GET /v1/services/receivables call. Read more How to handle Finnish consumer invoicing.

Use GET /v1/services/receivables to fetch the status of the activation to see when the service is activated. Or register a webhook to get a callback notification from Maventa when the service gets activated (or rejected).

Receivables Management service can also be activated through our user interface.

How to handle Finnish consumer invoicing

How to change company information

If you wish to change or update any information you will need to contact our support. Later on there will be an API for this as well.

Assignments

From all the invoices sent through the Receivables Management service an assignment is created. Assignment is something through which the company can follow up the process on the Visma Financial Solutions side and if the invoice gets paid on time by the debitor (receiver). Assignment is also used for all the communication between the sender company and Visma Financial Solutions. To link the sent invoice and assignment together, there is parameters reference_ids and invoice_id in the assignment having the invoice uuid of the sent invoice. There are 3 different statuses the assingment can have:

1. Open - The assignment is open and Visma Financial Solutions is monitoring the receivables. On the other words the invoice hans’t yet been paid.
2. Partially closed - The assignment has been paid but the customer still has open charges which Visma Financial Solutions will continue to collect.
3. Closed - The assignment has been paid and no charges are open. Visma Financial Solutions has tranferred the money to company’s account.

[
  {
    "id": "fa9781ba-20d1-4677-a125-f04bff7bbac0",
    "status": "open",
    "debtor": {
      "name": "Hanna's Test Company"
    },
    "due_date": "2020-04-20",
    "issued_at": "2020-04-01",
    "number": "64488",
    "sum": 12.3,
    "paid": 10,
    "currency": "EUR",
    "created_at": "2020-04-15T05:47:07Z",
    "updated_at": "2020-04-15T21:01:18Z",
    "closed_at": null,
    "reference_ids": [
      {
        "type": "agency_id",
        "value": "078dbb88-ef8e-4115-8260-c8a542aaa87c"
      },
      {
        "type": "invoice_id",
        "value": "f6dcf18d-a1bd-4e72-bb8a-80908527b6c8"
      },
      {
        "type": "number",
        "value": "356241887794"
      }
    ],
    "events": [
      {
        "id": "c0c56722-a28b-49d1-aa87-1c4d7f3cf1af",
        "type": "paid",
        "data": {
          "sum_paid": 10,
          "booked_at": "2020-04-16",
          "archive_number": "12345"
        },
        "party_id": "938fc79f-9c00-47af-8507-cdf15838aa96",
        "seens": [
          {
            "seen_at": "2020-04-15T22:00:06Z",
            "seen_by": "Visma Financial Solutions FI"
          }
        ],
        "created_at": "2020-04-15T21:01:18Z",
        "happened_at": "2020-04-16T00:00:00Z"
      }
    ]
  }
]

REST API for assignment handling.

Events

Parties connected to an assignment (company and Visma Financial Solutions) can add events to communicate changes to the assignment. Events describe what has happened to the assignment for example when the customer pays the invoice Visma Financial Solutions will add an Paid event to the assignment. Events can also be used to update assignment information from the sender side like requesting a new due date or inform direct payments. Events can be considered as a communication channel between Visma Financial Solutions and your company.

We highly advice to automate these events as far as it is possible from the ERP. At least paid and credit_note events for making sure these will be commnunicated always to the Visma Financial Solutions without needing to rely end user to remember to do these through our UI.

REST API for event handling.

What can be done using the events

  {
    "type": "paid",
    "data": {
      "sum_paid": 200.5,
      "booked_at": "2019-01-04",
      "archive_number": "12345"
    }
  }

  {
    "type": "freeze",
    "data": {
      "frozen": true,
      "end_date": "2019-01-04"
    }
  }

Embeddable user interface and Receivables service

We have done our own implementation for the Receivables API that serves our UI users. The UI is done for our embeddable user interface (EUI) and can therefore be taken easily into use as is by any integrator. For more information about our EUI and how to take that into use can be found here

With customizable EUI you can decide how and in what part of your ERP product the Receivables service will be embedded and be available to your users.

You can show the whole EUI with the main navigation bar for users to access the Receivables service:

You can decide to hide the main menu and have a direct link to only open up only the Receivables service pages:

Or then you can only show the details of one assignment. This could then be part of the sent invoice providing easy and quick access to all the necessary information related to that particular invoice:

Tips for the integrators

Closing the service

Service can be closed by either deregistering the profile from the RECEIVABLES network through the API or then by closing the service through the user interface. After the service is closed new invoices sent are not routed through Visma Financial Solutions anymore. Visma Financial Solutions will still handle the open assignments.

NOTE! Even though the user closes the service, it might still be necessary to allow the use of the APIs in order for the user to continue following up the remaining open assignments and to perform events if necessary.

Reopening the service

Reopening the service needs manual handling and therefore being in contact with our support.

Useful links

Reskontravahdin asiakasohje (in Finnish only)

How scanning service works

The scanning service receives invoices either as PDF (by email) or as paper invoices, which are scanned into PDF. An Optical Character Recognition (OCR) system is used to interpret keywords from the invoices.

After the OCR interpretation and validation, all invoices are checked in an extra quality control. If the program finds any deviation, the invoices will be manually checked one more time.

The resulting XML invoice and original PDF are delivered to recipient’s Maventa account, from where the recipient’s ERP can fetch them. It is important that the recipient always checks the accuracy of scanned invoices.

What fields are recognised from the invoice

Process flow

1. Company enables the invoice receiving (Maventa account settings)
2. Company opens the scanning service (Maventa account settings)
3. Company receives the e-mail address and post address to where suppliers can sent invoices for scanning
4. Supplier sends invoices to scanning service either via e-mail or post
5. Scan service receives invoices from the supplier and identifies the recipient
6. Scan service scans the invoices
7. Scan service delivers the XML file together with the original PDF to Maventa
8. Maventa delivers the file to recipient’s Maventa account

The standard delivery time is within 36 hours. Files are transmitted to company’s account every 15 minutes.

Opening the service

The scan account can be opened over the API or through the UI from company settings.

SOAP API: scan_account_order

REST API: POST/v1/company/profiles

{
  "network_settings": {
    "return_email": "example@example.com",
    "return_address": {
      "post_code": "00000",
      "post_office": "cityX",
      "street_address": "Street 1"
    },
    "other_docs": false
  },
  "network": "SCAN",
  "profiles": ["INVOICE_AND_CREDIT_NOTE"]
}

Before opening the scan account for a company, make sure company has the receiving setting turned on. Scanned invoices from the scanning service are delivered to the Maventa customer like any other incoming e-invoice and for this reason the invoice receiving must be on to enable scanning.

New scan account requests are processed every night. Scan account is opened and Scan ID number is created automatically by the Maventa based on the customer organisation number.

When opening the scanning service, customer needs to specify return e-mail address where all other material than invoices are delivered by the scanning service. Changes to company return address or other information can be made using

SOAP API: scan_account_order

REST API: PATCH/v1​/company​/profiles​/{id}

How suppliers can send invoices to scan service

Company informs their suppliers about their scan address they have received when service is activated. Scan address contains the company’s scan ID number that is used to identify the recipient.

There are two ways suppliers can send invoices to the scanning service to be scanned; by e-mail or by post.

By E-mail

Finland, Sweden, Norway, Denmark and Netherlands

Requirements for sending

• Only one invoice per pdf file
• There can be many pdf files per e-mail but only when the recipient is same in all of them
• There does not need to be Scan ID number in the invoice image itself, e-mail address that contains scan ID is enough to identify the recipient
• After e-mail is sent, sender will receive notification e-mail of sent e-mail (notification is automatic reply from the e-mail service)
• If e-mail cannot be handled, address is not found or there are no PDF attachments in the e-mail, sender will receive an additional error notification after the first notification

By Post

Finland, Sweden and Norway

Scan service identifies the recipient using following information found from the invoice image if invoice is sent by post:

• Organisation number
• Company name
• Company OVT code

Scan ID and Scan addresses

Delivery of materials

Scan service delivers only invoices and credit notes electronically. When a customer opens the scan service they need to specify a scan return address that is used to deliver none invoice materials. Marketing materials are not delivered.

Delivered as e-invoices:

• Invoices
• Credit notes

Delivered via e-mail:

• Reminders
• Agreements
• Invoices and credit notes that are missing mandatory information

Delivered via post:

• Materials that don’t fit to the scanner

Thrown away:

• Marketing materials such as ads, catalogues brochures

See your used price list for the relevant delivery prices.

Error handling

End users can report interpretation errors by email to support@maventa.com. Support contacts the validation teams at scan service provider to use auto learning process, where interpretation is manually changed so that invoices are correctly interpreted the next time.

If there are problems on the invoice, users can also request rescanning.

Closing the service

Closing the service (disabling the scanning service) is done by calling API or via the UI’s scan account page.

SOAP API: scan_account_disable

REST API: DELETE/v1​/company​/profiles​/{id}

After the scan account is closed in the Maventa, information is sent to the scanning service provider. Service provider receives closing requests every night. When the account is fully closed the scan e-mail address stops working. If some party still sends material to it they will receive an automatic reply that the e-mail address is no longer in use.

Material sent by post will be scanned and delivered to the recipient by e-mail (to the return e-mail address) for the next 60 days and after that everything is destroyed. The scanning service does not inform the senders that their paper invoices were not delivered. When closing a scan account, the company should inform their suppliers about the way the company will receive invoices from them in the future.

What is Detect service

Detect is an automated checking service for suppliers and purchase invoices. Detect checks and notifications aim to support companies in supplier management, automating invoice handling, spotting potential fraud attempts as well as in general preventing mistakes in payments and bookings. The service is integrated as part of invoice receiving, so the notifications can be shown to the company always in the right context.

Currently the following checks are available in the service

• VAT check - If value added tax on the invoice, see that the supplier is found in the VAT register
• Supplier activation check - For scanned invoices, check if supplier could have sent the invoice electronically
• BID check - Check the sender business identifier against central business and bankruptcy registers. Available for invoices from Norwegian and Finnish senders.
• Warning list check Check the invoice sender against registers containing warnings against suspected fraudsters and business scams/swindles.

How does Detect service work

Detect is integrated as part of incoming invoice handling over the REST API.

• Detect checks are first activated by the receiver company. After this all company’s incoming invoices coming to Maventa are automatically checked. When the invoice becomes available for download, also the check results are available to fetch and to display to company.

• Maventa runs the checks and provides ready made descriptions, notification statuses and messages for them. Texts and translations are available in EN,NO,FI,SE,DK,NL.

• Activation and showing the check results takes place on integrated system (company’s financial software/ERP).

Integration requirements

Process

• Check activation to take service into use
• Getting the check results when invoices are received (based on invoice id)
• Displaying the check results to user

Contractual requirements

• Customer has accepted the Terms of Service for Maventa
• Customer has accepted the General Disclaimer for the service (available at the end of this guide)

Billing set up

• Please discuss your integration contact point about the pricing related to the use of service.

Building the integration

Detect uses the AutoXchange API (REST)

• Stage
• Production

Authentication:

General instructions for REST API authentication are explained here

For Detect, use "Authenticate as a company" - option and select the authentication scope "analysis".

Endpoints:

• Activate and deactivate checks: PATCH​/v1​/company​/settings
• See check activation status: GET/v1​/company​/settings
• See all available checks, their description and possible result messages: GET/v1​/analysis​/definitions
• Get check results: GET/v1​/analysis​/{id}

Example flow - activation & usage

1. Service activation

To take the service into use for company, user activates the checks they want to start using. Note that before activating the service the user needs to be shown and accept the General service disclaimer.

DO:

1. Show user the General service disclaimer.

2. Show available checks and their descriptions
   • Use GET/v1​/analysis​/definitions endpoint to see the available checks and information related to them
     • all the information e.g. what registers are used for which checks are available over this endpoint.
3. Activate the checks for a company
   • Use PATCH​/v1​/company​/settings to activate checks
   • Give the checks you want to activate (array of strings) for the specific company
   • After you receive status OK , the checks have been successfully activated. From now on these checks will be automatically triggered for the company’s incoming invoices

• Use GET/v1​/company​/settings to return the status of the company settings and see which checks are activated for the company

Example check activation in user interface

2. Checks are run on incoming invoices

After activation all company’s incoming invoices are automatically checked. When running the checks is ready, the invoice is released to customer’s inbox and check results are made available over the REST API.

Invoice and the attachments are downloaded as usual (see invoice receiving ). Detect check results are downloaded with an own API call.

DO: Fetch the check results from Maventa

• Use GET/v1​/analysis​/{id} to download the check results based on invoice id

About result handling

• Response includes results for all the checks company has activated - only one call is needed to get all the results
• The flow is built in a way that invoices are not released to be listed or downloaded before the checks are run. This means that when you are able to list the new incoming invoices also the check results are ready for fetching.
  • If there are issues with running the checks (e.g. external register down) checks are tried to be run again
  • invoice waiting time max 4 hours - if the check could not have been run before that the analysis status shows as "RUN_FAILED"
• Analysis_result_status tells about the result of the check. If there is something to notify on the invoice generally status WARNING is used, it indicates there is something to display to user
• Note that there are also cases where check is not applicable, for example supplier activation is only run for scanned invoices, as well as cases where check could have not been run because of missing data, which means that Detect cannot tell what the check result is. See all the available result statuses under Check statuses -chapter in this guide.

3. Notifications are displayed to user

After check results are fetched, relevant notifications are shown to user.

If something is spotted on the invoice, this is shown to user by notification message as part of handling the incoming invoices.

DO: Use analysis_result_status to define what messages to show to user.

• Display message to user in relevant place in your system. This can be e.g. as part of views of invoice listing, invoice booking or invoice approval.
• See all possible results over GET/v1​/analysis​/definitions endpoint

Example result visualisation in user interface

4. Check/service closing

Same method that is used to activate the checks is used to deactivate them:

• Call PATCH​/v1​/company​/settings to change what checks are used

Closing the service happens by deactivating all the checks.

Check statuses

During the checking process checks can also have a state PENDING, which means that check is waiting for execution or being retried. This state is an internal intermediate state that is used inside Maventa only. This state should usually not be visible for integrators. When the invoice becomes available for listing and downloading the checks should always have one of the final states described in the table above.

General Disclaimer

Visma does not warrant that the customers use of the check services will be uninterrupted or error-free, or that the service and/or the information obtained by the customer through the Services will meet the customers requirements. The customer acknowledges and agrees that the check services will evolve over time and that functionality may be added and removed from time to time. The customer assumes sole responsibility for results obtained from the use of the check services and for conclusions drawn from them. Visma shall have no liability for any damage caused by errors or omissions in any information, instructions, warnings or flags provided to the customer in connection with the check services, or the customer’s actions or non-actions in response to such information.

Useful links:

• Detect Guide, for warning list
  • details of the warning list check and the used warning registers
  • this guide can be linked to customers directly or it can be used as a basis for writing user support documentation.
• Fraud reporting
  • As part of the warning list check Detect uses fraud reports from customers. See more details of fraud reporting and how to integrate to it.

Latest version

1.2.7157 (2019-08-06)

• Support for Finvoice 3.0 and Teapps 3.0 as download format

Download maventa-connector-installer.exe

Old versions

We do not recommend using old versions of Maventa Connector, please always use the latest available version. For special cases we keep some old versions available:

1.2.6690 (2018-04-26)

• Fixed LastDownloadSent timestamp to be culture agnostic

Download maventa_connector_installer_2018_04_26.exe

1.2.6675 (2018-04-11)

• Fixed thread handling when service is terminating
• Limit sending threads to configured value (default is 2)

Download maventa_connector_installer_2018_04_11.exe

Security

Connector’s security depends 100% on the OS security and folder privileges that it is running on. Connector client program moves documents between a folder and Maventa API using HTTPS same as all other ERP traffic. As the client program only makes API calls and copies files between API and folder and is triggered from the OS side there are no additional security aspects to consider as there are no incoming ports the software listens to. All local users that are given access to the filesystem that contain the configuration files can read the contents (API keys) thus the application should be protected from the OS side users using folder permissions. The program is using an old framework so software framework itself is outdated and this should be taken into consideration when thinking about using it.

How to send email invoices

Email is the first fallback route that our automated routing tries when it cannot find a way to send the invoice as an e-invoice. Routing order is the following 1. as an e-invoice 2. as an email 3. through the print service. Email route can also be forced if the desired way to reach the receiver is email. This can for example be a case for consumer invoicing when the recipient doesn’t have a way to receive invoices electronically through netbank (Read more about consumer invoicing).

Email sending is by default enabled on all company accounts. If needed it can be disabled from company settings or then invoice by invoice in sending. More about the disabling here.

Automated routing for emails

Email route is used when sending as an e-invoice is not possible. To be able to route invoice as an email the receiver’s email address needs to be present in the XML.

Forced email route

It is possible to force the invoice to be sent as an email by using invoice_put_invoice_with_metadata or POST /v1/invoices methods for sending. In the metadata other routes are being set as disabled to force email route. Also the receiver’s email address can be given in the metadata. Email address given in the metadata will be used instead the one in the XML.

Forcing to email route is also possible with certain XML formats:

S-EDI: If OutputMedia is set as “PDF” only e-mail route is enabled

Sending settings

There are 3 choices from which the sender can choose how they want their e-mail invoices to be send out. These e-mail settings can be changed via UI or using configure_company or PATCH /v1/company/settings API methods.

• Send all invoice e-mails with a link to download PDF:

Selecting this option means that the invoice e-mail will contain a link to download the invoice from Maventa service. There is also a passcode on the email that the receiver needs to give behind the link to access the invoice. When the receiver clicks the link and open the invoice, the sender receives a notification e-mail.

• Send all invoice e-mails with attachments:

Selecting this option means that all invoice e-mails will contain an image of the invoice in PDF format. Note that the total sizes of attached documents in an e-mail must be under 5 megabytes. If the attachments are larger, no attachments will be attached but instead the receiver needs to download using the provided link in the e-mail. Note! There will always be also the link to download because there might be some unexpected issues showing attachments and in this way we will ensure that the receiver will always get the attachments.
Virtual barcode is also added into the email body when sending invoice with image attached.

• Send all invoice e-mails with invoice objections:

By selecting invoice objections, the receiver must accept the invoice before being able to view any payment information. Receiver can also choose to decline the invoice, with the option to notify sender the reason for the decline. When any changes occur to the invoice, for example, the receiver accepts the invoice, the sender receives a notification e-mail and the status in Maventa is updated accordingly.

Message to the email receiver

Sender can define a message and define contact details that are shown in the email body either through API or via our UI. When using API use either configure_company method with giving the information in the parameters message_from_sender, contact_person, contact_email and contact_phone, or PATCH /v1/company/settings.

Note! When you define a contact email address we will send a confirmation email to this email address where you need to confirm that the address may be used for that purpose.

Language of the email

Email language depends on the input format (XML) and how language is set there. We currently support the following languages: Finnish (FI), English (EN), Swedish (SE), Norwegian (NO), Danish (DK) and Dutch (NL). Not all are according to the ISO 639-1 codes but we hope to get support soon for at least SV, NN, NB and DA soon.

Click the XML your product is sending from the list below to see how the language of the email invoice is defined:

Email reminders

Sender can specify how often a reminder email is sent if the invoice has not been accepted, declined or the link has not been opened by the receiver. This does not apply if the invoices are sent as attachments.

configure_company email_remind_freq or PATCH /v1/company/settings “reminder_frequency”.

Reply to

If you have defined a contact email that is used as the reply-to address for email invoices. If not defined the fallback is the user’s email address (either API user’s email or an email address from the XML if defined). If that does not exists, fallback is the company email address.

Error handling

If the email bounces due to for example a non existing email account the invoice will go into error state. The sender will be notified by email as long as the email notifications are not disabled. Error is also returned through API when asking after status of the sent invoice.

Note that the invoice will not go into error state if the recipients email box is full, or if recipients email marks the email as spam. If you will be sending out an email invoice with big attachments it is good practise to contact the receiver afterwards and making sure they really received the invoice to their email box.

Disable email sending

Email sending is by default enabled on all company accounts. You can either disable the whole email sending possibility from company settings or then disable it invoice by invoice in sending.

To disable the whole email invoice sending use configure_company API method and set parameter send_invoice_email to 0, or with REST API use PATCH /v1/company/settings set “enabled” as false under the “send_invoice_email”. By choosing this setting the email route is skipped in automated routing.

To disable the email sending invoice by invoice use invoice_put_invoice_with_metadata or POST /v1/invoices methods for sending and set the email route as disabled. This will skip the email route for that particular invoice. If you are using some other method for sending also leaving the receiver’s email address empty will cause the email route to be skipped.

By using EUI you have the possibility to skip part(s) of the API integration towards us and still provide your customers everything directly from your product. Your end customers can also get a possibility to have a quick access to our new features and services without them having to wait for developement and changes on the ERP side thus reducing the time to market of our new cool features. Embedding the EUI to be part of your product is really easy and does not require lot of time or development resources.

Even though almost everything can be done via the EUI there is still some functions that we highly recommend that the ERP does through the normal Maventa API integration:

• Providing a easy on-boarding of customers - register to Maventa “by touch of a button”
• Sending and receiving invoices (and other documents)
• Different invoice handling workflows like approving invoices
• Adding new users to Maventa company account

Basically all the rest can be done via the EUI:

• Listing of invoices and documents and viewing their details
• Resending and rerouting invoices
• Toggle Maventa settings
• Register to receive through different networks
• Search for receiver’s e-invoice addresses
• Listing of consumer agreements (Norway)
• Enable (and use) functionalities like:
  Consumer invoicing handling (currently only for Norway),
  Receivables Management Service for Finnish companies, Detect,
  Visma Scanner

How does the EUI look

How to take the EUI into use

Decide what to show to your customers and how

First you should think a bit what do you want your end customers to see. What parts of the EUI they need? And then decide how to show those views. Should you add one button to open up the whole EUI and let customers navigate themselves to the page they need or should you show different views in different parts of the ERP depending on the context (Settings view embedded into the part which shows ERP’s settings, and invoices lists where there are invoices listed on the ERP)?

Read more about the customisation of the EUI. Our team is happy to assist you in deciding what would be the best fit for your ERP. If you want help in deciding or if you have made some decisions youself contact Maventa support and ask for an EUI ERP profile. We will then set up you profile based on your preferences.

Decide how to embed

It is really easy to embed. We offer two different solutions for embedders, one where you can include a script tag on your HTML page within your product, and another one where you can use an iframe (or similar solution) to embed the EUI. First one we recommend to those products that are running in the user’s browser because with the iframe solutions there might (and most likely will) be problems loading cross-domain content. Both of these embedding methods, script embedding and Iframe embedding, explained in details.

What is common in both ways to embed are the domains listed below and that you will need to get an access token for the company.

We currently host the EUI under 3 different domains:

Production environment:

• autointerface-embeddable.maventa.com
• autointerface-embeddable.autoinvoice.visma.com
• autointerface-embeddable.visma.net (Visma internal use)

Testing environment:

• autointerface-embeddable-stage.maventa.com
• autointerface-embeddable-stage.autoinvoice.visma.com
• autointerface-embeddable-stage.visma.net (Visma internal use)

Fetch an access token for the company

Authentication and access to the EUI is done using token based login (based on company_uuid, user_api_key and vendor_api_key).

The token to open EUI is fetched using the AX Oauth2 endpoint using the following parameters

Endpoint for getting the token:
Testing: https://ax-stage.maventa.com/oauth2/token
Production: https://ax.maventa.com/oauth2/token

curl -X POST "https://ax-stage.maventa.com/oauth2/token" 
-H "accept: application/json" 
-H "Content-Type: multipart/form-data" 
-F "grant_type=client_credentials" 
-F "client_id=company_uuid" 
-F "client_secret=user_api_key" 
-F "scope=eui" 
-F "vendor_api_key=erp_vendor_api_key"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudG......",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "eui"
}

When you have an access token you can then use it in the emdedding solution you have chosen, script embedding or Iframe embedding. Both are explained below:

Method 1 - Script embedding

Add script tag <script> in your browser page with the following content:

<body>
    <div style="height: 1024px" id="eui-container"></div>
    <script src="http://autointerface.visma.net/embed"
            data-token="eyJ0eXAiOiJKV1QiLCJraWQiOiJjODJhZTdiZTU...."
            data-container-id="eui-container"
            data-default-path="/invoices"
            data-profile="my_erp_profile_name"
            data-locale="en"
            data-setup-top_menu="false"
    ></script>
</body>

In the above example the EUI is opened directly to the invoices page, language is set to be english and the whole top menu is hidden.

With this embedding method there is no way to renew the token. This means if the user has the EUI open for over one hour the session will be unusable and needs to be restarted with a new authentication. So remember that the token will expire in one hour and user will be kicked out. When that happens customers should be able to refresh the page and gain access again.

Method 2 - Iframe embedding

The endpoints for the process are the following:

Start monitoring the token expire time for automatic session renewal

While the user’s EUI session is active you need to act when the token is about to expire. The expires_in attribute in the token response tells how long the access token is valid. To be sure deduct a few minutes from the time to not run into issues. It’s important to stop the renewal process if the user closes the EUI session or the user have logged out in some other way.

The provided token in the initial request will be valid for one hour and if the token is not renewed the users session will end when the token expires. This means if the user has the EUI open for over one hour the session will be unusable and needs to be restarted with a new authentication. To prevent this the token can be updated for the user in the background without the user noticing anything (Step 4). To be able to renew the token the first thing to do is to pass a unique ID as the session id for each authentication that is initiated, this to be able to associate to the session on renewal. The unique ID is given in the session_id parameter on the initial authentication request (see the step 3).

token = fetch_token

setTimeout(function(){
  if(user_session_active()) {
    renew_token();
  } else {
    // user has closed the EUI window
  }
}, token.expires_in - 60*5);

Open the EUI session in a browser component

When you have a token you are ready to open EUI in a browser window.

Depending on the browser component capabilities it varies a little how the EUI session can be initiated. The token can be put in either the POST body or in the Authorization header as a Bearer token.

curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/token" 
-H "Content-Type: multipart/form-data" 
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9......" 
-F "profile=my_erp_profile_name" 
-F "locale=no" 
-F "redirect_to=/invoices" 
-F "session_id=erp_users_session_id"

<!DOCTYPE html>
<html>
<head></head>
<body>
  <form action="https://autointerface-embeddable-stage.maventa.com/authentication/token" method="POST" target="_blank">
    <fieldset>
      <legend>Authentication using token</legend>
      <br/>
      <label>token:</label>
      <input type="text" name="token" size="100" />
      <br/>
      <label>session_id:</label>
      <input type="text" name="session_id" size="70" />
      <br/>
      <label>redirect_to:</label>
      <input type="text" name="redirect_to" size="70" />
      <br/>
      <label>profile:</label>
      <input type="text" name="profile" size="40" />
      <br/>
      <br/>
      <input type="submit" value="Log in"/>
    </fieldset>
  </form>
</body>

Renew the token for an existing session

When the token is about to expire a new token needs to be obtained exactly the same way as in (Step 1).

The token then needs to be passed to the renew endpoint in EUI, combined with the session_id generated in the initial request. If you are able to extract/use the session cookie from the browser component it’s possible to use that when renewing the token, then there is no need to pass and use the session_id.

curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/renew" 
-H "Content-Type: multipart/form-data" 
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6InVzZXIiLCJ1c......" 
-F "session_id=erp_users_session_id"

function start_user_session(session_id, token) {
  monitor_session_token(session_id, token.access_token); // Start waiting for the token to expire
  open_browser_window(session_id, token.access_token); // Open browser component with the token
}
 
function monitor_session_token(session_id, token) {
  setTimeout(function(){
    if(user_session_active(session_id)) {
      renew_token(session_id);
    } else {
      // user has closed the EUI window
    }
  }, token.expires_in - 60*5);
}
 
function renew_token(session_id) {
  token      = fetch_token();
  if(post_new_token_to_eui(session_id, token.access_token) == 200) {
    monitor_session_token(session_id, token);
  }
}
 
token      = fetch_token(); // Fetch token from AX
session_id = generate_uuid(); // Generate an ID for future reference
 
start_user_sesion(session_id, token);

Customise your own view of the EUI

EUI is highly customisable and every ERP can create their own look and feel of it. You can decide what to show to your end customers through the EUI and what should be hidden from them. For example if there is no invoice receiving capabilities in the ERP, received invoices list can be hidden and as well all the invoice receiving related settings. Customised view will greatly improve the user experience by always provide only useful information to the end customers. Customisation of the EUI is a really cool feature.

Customisation can be done using the ERP profiles and optional setup parameters:

ERP Profiles

ERP profiles are the main way to customise the views and are created for each ERP using the EUI. Using profile in a call toward EUI will load the ERP specific view. ERP profiles are created and modified by Maventa team based on the ERP’s needs and requirements. So before you start to build the integration towards the EUI, please contact Maventa support and ask for an EUI profile. One ERP can have multiple profiles. For example one for each version of the system or if you have different customer groups and would like to show them different content based on what functionalities they have in use.

...&profile=name_of_the_profile

When we add something big to the EUI for example a new service or functionality we will always contact all the EUI ERPs if they wish to have that new service visible also to their customers. Using EUI comes really handy by reducing the time to market of new services. Of course it is good to keep in mind that some of the new services might also require some changes from the ERP side or to the API integration but some services work just fine only through the EUI.

Setup parameters

Profiles are great way of setting up the EUI look and feel, but if you want to have further control use the EUI setup parameters. EUI setup parameters have the same structure as the profiles and those can be used in combination with a profile. EUI setup params will override any setting from the profile so if you want to have a bit different views for one specific customer you can do it by using setup parameters. Empty values for any EUI setup parameter, equals false.

Let’s say that you have few customers that do not receive invoices through your ERP at all and you want to provide them a different view than for the rest of your customer by hiding all that is related to the invoices receiving:

• To hide received invoices list
• To hide settings for invoice receiving

EUI setup parameters will look like:

...&setup[sections][invoices][inbound]=false
&setup[sections][settings][invoice][receiving]=false

Direct URLs

With direct URLs customers can be redirected straight to the page you want. In the part of the ERP where invoices are handled could be a direct link to the invoices list of the EUI. And in the part where there are all the setting there could be a link to open up a settings page of the EUI. You can also have direct link for only showing details of an one invoice if you for example want to integrate the EUI invoice details as being part of the invoice details shown in the ERP.

Supported browsers and their versions

• Chrome
• Firefox
• Safari
• Edge

When the service is in use, loans can be withdrawn just by a click of a button without any loan negotiations or long waiting time. The service calculates the funding available against invoices sent. It is 80 % of the total amount of the invoice. If the total amount is 10 000 €, the company will receive a loan promise of 8 000 €. The limit granted to the company can be up to 1 million euros. All sent invoices need to have OP’s bank account details and transfer clause added but other than that basically all the rest is handled on Maventa and OP side.

The interest is paid only on the daily balance of the withdrawn loan, there are no other fees or costs involved. The service’s interest is 1% to 2% monthly rate, applied to your daily credit balance. All credit operations are automated and each invoice payment will automatically reduce the credit balance, thus effectively lowering the interest payment.

OP Laskulaina - Invoice Credit Service is available to all Finnish companies, independent of which bank’s services they are using.

Step by step process for OP Laskulaina

1. Activation of the service. When the service is activated all the sent invoices are routed through the OP Laskulaina Service (with few exceptions).
2. Invoices are sent from the ERP to Maventa the same way as before but all the invoices need to have OP’s virtual IBAN and transfer clause. See requirements for the ERP.
3. When an invoice is successfully sent to the receiver Maventa gives the invoice information to OP and then OP grants a loan against those invoices (How much loan do I get against my sent invoices). Note! Sender is responsible for handling invoice sending related errors and for making sure the invoice reaches the receiver. In some cases the invoice might end up in the error state days after it was sent out successfully. Read more about the error handling
4. Each sent invoice will increase the credit available and each payment of the invoice will decrease it
5. Receiver pays the invoice with OP’s payment information. If there is loan withdrawn or interest to pay (interest is capitalized at the turn of the month) the money will be used for that. If no loan is withdrawn or there is no interest left to pay, OP will pay the full amount directly to the sender. Order for using the money paid by the receivers is: Interest payment, loan repayment, paying to the sender.

Repayment of the loan

If a company has withdrawn a loan or there is interest to pay the money OP gets from the invoice payments will be used for those. If no loan is withdrawn or there is no interest left to pay, OP will pay the full amount directly to the sender.

The service’s interest is 1% to 2% monthly rate, applied to your daily credit balance. Each invoice payment will automatically reduce the credit balance, thus effectively lowering the interest payment. Loan interest is capitalized at the turn of the month. If there has been a loan withdrawn even for a day during the past month there will be interest that is paid from the invoice payments that comes into OP’s account at the beginning of the month.

Repayment % (how big part of an invoice is used for the loan repayment) is also something that the company can decide themselves within certain limits.

Requirements for the integrating ERPs

• Being able to switch using new IBAN (OP’s virtual IBAN) on all sales invoices sent from the customer’s account. OP’s virtual IBAN needs to be the one receiver will use to pay the invoices.
• Being able to add a transfer clause to the invoice XML. Note! Presence of the transfer clause is verified by Maventa and if missing invoice will end up in the error state. Transfer clause needs to be exactly the same as what the activation API will return. OP’s virtual IBAN in it is the only thing that can be changed to match the company specific IBAN. From the IBAN we only check the part from the beginnig that identifies the service (FI** 5984 5120 ** **). Field for transfer clause in Finvoice is FactoringFreeText (or InvoiceFreeText) and in TeappsXML HEADER/FACTORING_INFORMATION/FREE_TEXT (or HEADER/FREE_TEXT)
• Providing vendor_api_key in every send
• For business to business (B2B) invoices the receiver’s business id (y-tunnus) is mandatory information
• For business to consumer (B2C) invoices the consumer’s customer number and name are mandatory information
• There needs to be least 3 weekdays until the due date
• Invoices in other currencies than EUR need to have their own handling (can’t use OP’s virtual IBAN on those)
• Handling for credit notes: One to one credit notes (only one invoice credited with one credit note). Credit note must have reference for the original invoice (Finvoice 3.0 OriginalInvoiceNumber, TeappsXML HEADER/CREDIT_INVOICE_NUMBER)
• Handling for payments done directly to company’s own account
• Good error handling in place for sent invoices
• Being able to read and handle SEPA XML

Opening the OP Laskulaina Service

Step 1: Make sure your ERP meets all the requirements stated in the previous chapter. Before starting to build the integration you will need to be in contact with our support. The service requires vendor specific configurations from our end to enable the usage of the API.

Step 2: Call GET /v1/services/op_invoice_credit/offer to get an offer for OP Laskulaina before activating the service.

This step is optional to do but allows you to build a better customer experience. Using this method the customer can find out how big of a credit limit they would get from OP, before going through the whole activation process. And if they don’t get an offer, they don’t have to go through the activation process to find that out.

Step 3: Call PUT /v1/services/op_invoice_credit to initiate the activation. In order to get the service activated an electronic agreement between the company and OP needs to be filled and signed by a person having authorized signatory rights for the company.

Signing of the electronic document requires authorized persons to authenticate themselves using their personal online bank identifiers or mobile signature. Authentication and signing process is done on the OP side through their own webpage. This method returns a link (activation_url) where the end customer should be redirected to do the signing.

Step 4: Call GET /v1/services/op_invoice_credit to finalize the activation.

This method will return you the OP’s virtual IBAN and the transfer clause that both need to be added to all the invoices sent from that customer’s account. So one pre-requirement to use this service is to be able to create new accounts on the ERP side and to switch using that account number on the sales invoices.

Using the OP Laskulaina service

Once the service is activated and the customer has sent some invoices, they will get available credit and can make withdraws when needed.

You can freely choose what kind of user interface to build for checking the amount available credit and making a withdrawal. For inspiration we have built something ourselves.

Check the available credit

Use GET /v1​/services​/op_invoice_credit​/available_credit to check the credit balance.

Make a loan withdrawal

Use POST /v1​/services​/op_invoice_credit​/withdrawal to make a withdrawal

Additional settings

There are additional settings you can show to the user and allow them to modify if they want.

• b2c_enabled: By default B2C invoices are just sent through the service but those are not increasing the available credit. Depending on the situation OP can also give loan against B2C invoices. If the customer wants, they can enable this feature.
• payment_percent: By default the payment percent is 100% which means that if the customer has any withdrawn loan, the invoices getting paid will be fully used to pay back the loan. Depending on the situation, OP can also allow a smaller payment percentage. For example if the payment percentage is 80% it means 80% of each incoming payment will be used to pay back the loan (if any is withdrawn). And 20% of each payment will always be directed directly to the customer, even if there would be some withdrawn loan to be paid.
• interest_rate: Depending on the situation OP might be able to give a smaller interest rate to the customer. Changing this setting will take that smaller percentage into use.
• credit_limit: Depending on the situation OP might give an increase to the total possible credit limit for the customer. Changing this setting the new credit limit can be taken into use.

Check current settings and get an offer

Call GET /v1/services/op_invoice_credit/settings to see what the current settings are and what is the offer OP could give. The method returns two JSON objects “current” and “offer” with the same exact structure.

Modify settings

If there is an offer where some values are different, and the customer would like to update their settings, you can call POST /v1/services/op_invoice_credit/settings with the desired values.

Type of invoices not routed through OP Laskulaina

• The service only grants loan for invoices having EUR as their currency. If there is a need to send invoices in other currencies then do not use OP’s IBAN and transfer clause on those. Invoices in other currency than EUR having OP’s virtual IBAN will end up in error state.
• Other exceptions are invoices to non-Finnish receivers. Those are routed through the service, and you can use OP’s IBAN and transfer clause on those, but no loan against those are granted nor they are used for loan repayment.

Error handling in OP invoice credit service

Sender is responsible for handling invoice sending related errors and for making sure invoice reaches the receiver. We highly recommend to have a proper error handling in place on the ERP side. Possibility to reroute an failed invoice (API or UI).

Account statement handling - SEPA XML

OP invoice credit account statement is in SEPA XML format. The SEPA XML file is fetched using an API endpoint GET /v1/services/op_invoice_credit/account_statement and by defining the date for which to fetch the transactions (YYYY-MM-DD). Even though this file is not coming through the normal WS channel like all the other account statements it should still be processed in the same way / in the same process by the ERP. Payments, loan repayments and interest payments should be targeted correctly in the ERP side to mark the invoices as paid.

File is fetched from the previous day and it is returned only when it is ready (ready = no unclear/untargeted payments). If the file is not returned it should be refetched until received. In most cases the file from yesterday should be ready by the next morning. Good practise is to fetch it for example at 7 o’clock in the morning and if not received try every hour until afternoon and then a few times a day for the next 5 days.
Empty file means that there were no transactions from that given day.

{
"code" : "invalid_parameter",
"Message": "Request parameters are invalid",
"Details": [
	"unmatched _payments"
	]
}

{
"code" : "internal_server_error",
"Message": "An internal error has occurred",
"Details": null
}

You can find the specifications for account statement here. And below we have examples on each of the events that can be present on the OP’s SEPA XML:

            <Ntry>
                <NtryRef>0</NtryRef>
                <Amt Ccy="EUR">2222.25</Amt>
                <CdtDbtInd>CRDT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2021-08-02Z</Dt>
                </BookgDt>
                <ValDt>
                    <Dt>2021-08-02Z</Dt>
                </ValDt>
                <AcctSvcrRef>211961</AcctSvcrRef> 
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>RCDT</Cd>
                            <SubFmlyCd>ESCT</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Cd>VIITESIIRTO</Cd>
                        <Issr>FFFS</Issr>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <AmtDtls>
                            <TxAmt>
                                <Amt Ccy="EUR">2222.25</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <BkTxCd>
                            <Domn>
                                <Cd>PMNT</Cd>
                                <Fmly>
                                    <Cd>RCDT</Cd>
                                    <SubFmlyCd>ESCT</SubFmlyCd>
                                </Fmly>
                            </Domn>
                            <Prtry>
                                <Cd>VIITESIIRTO</Cd>
                                <Issr>FFFS</Issr>
                            </Prtry>
                        </BkTxCd>
                        <RltdPties>
                            <Dbtr>
                                <Nm>MAKSAJA 1 OY</Nm>
                            </Dbtr>
                            <DbtrAcct>
                                <Id />
                            </DbtrAcct>
                        </RltdPties>
                        <RmtInf>
                            <Strd>
                                <CdtrRefInf>
                                    <Tp>
                                        <CdOrPrtry>
                                            <Cd>SCOR</Cd>
                                        </CdOrPrtry>
                                    </Tp>
                                    <Ref>00000000333180290261</Ref>
                                </CdtrRefInf>
                            </Strd>
                        </RmtInf>
                        <RltdDts>
                            <AccptncDtTm>2021-08-02T00:00:00.000Z</AccptncDtTm>
                        </RltdDts>
                    </TxDtls>
                </NtryDtls>
            </Ntry>

         <Ntry>
                <NtryRef>1</NtryRef>
                <Amt Ccy="EUR">2091.68</Amt>
                <CdtDbtInd>DBIT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2021-08-02Z</Dt>
                </BookgDt>
                <ValDt>
                    <Dt>2021-08-02Z</Dt>
                </ValDt>
                <AcctSvcrRef>211961</AcctSvcrRef>
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>RCDT</Cd>
                            <SubFmlyCd>ESCT</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Cd>CL_PMT_FROM_BUYER_CL</Cd>
                        <Issr>FFFS</Issr>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <AmtDtls>
                            <TxAmt>
                                <Amt Ccy="EUR">2091.68</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <BkTxCd>
                            <Domn>
                                <Cd>PMNT</Cd>
                                <Fmly>
                                    <Cd>RCDT</Cd>
                                    <SubFmlyCd>ESCT</SubFmlyCd>
                                </Fmly>
                            </Domn>
                            <Prtry>
                                <Cd>CL_PMT_FROM_BUYER_CL</Cd>
                                <Issr>FFFS</Issr>
                            </Prtry>
                        </BkTxCd>
                        <RltdPties>
                            <Cdtr>
                                <Nm>OP LASKULAINA/ OP VÄHITTÄISASIAKKAAT̈ OYJ</Nm>
                            </Cdtr>
                            <CdtrAcct>
                                <Id>
                                    <IBAN>FI4350000120469282</IBAN>
                                </Id>
                            </CdtrAcct>
                        </RltdPties>
                        <RmtInf>
                            <Ustrd>CL_PMT_FROM_BUYER_CL</Ustrd>
                            <Strd>
                                <CdtrRefInf>
                                    <Tp>
                                        <CdOrPrtry>
                                            <Cd>SCOR</Cd>
                                        </CdOrPrtry>
                                    </Tp>
                                </CdtrRefInf>
                            </Strd>
                        </RmtInf>
                        <RltdDts>
                            <AccptncDtTm>2021-08-02T00:00:00.000Z</AccptncDtTm>
                        </RltdDts>
                    </TxDtls>
                </NtryDtls>
            </Ntry>

           <Ntry>
                <NtryRef>2</NtryRef>
                <Amt Ccy="EUR">130.57</Amt>
                <CdtDbtInd>DBIT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2021-08-02Z</Dt>
                </BookgDt>
                <ValDt>
                    <Dt>2021-08-02Z</Dt>
                </ValDt>
                <AcctSvcrRef>211961</AcctSvcrRef>
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>RCDT</Cd>
                            <SubFmlyCd>ESCT</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Cd>CL_PMT_FROM_BUYER_INTEREST</Cd>
                        <Issr>FFFS</Issr>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <AmtDtls>
                            <TxAmt>
                                <Amt Ccy="EUR">130.57</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <BkTxCd>
                            <Domn>
                                <Cd>PMNT</Cd>
                                <Fmly>
                                    <Cd>RCDT</Cd>
                                    <SubFmlyCd>ESCT</SubFmlyCd>
                                </Fmly>
                            </Domn>
                            <Prtry>
                                <Cd>CL_PMT_FROM_BUYER_INTEREST</Cd>
                                <Issr>FFFS</Issr>
                            </Prtry>
                        </BkTxCd>
                        <RltdPties>
                            <Cdtr>
                                <Nm>OP LASKULAINA/ OP VÄHITTÄISASIAKKAAT̈ OYJ</Nm>
                            </Cdtr>
                            <CdtrAcct>
                                <Id>
                                    <IBAN>FI4350000120469282</IBAN>
                                </Id>
                            </CdtrAcct>
                        </RltdPties>
                        <RmtInf>
                            <Ustrd>CL_PMT_FROM_BUYER_INTEREST</Ustrd>
                            <Strd>
                                <CdtrRefInf>
                                    <Tp>
                                        <CdOrPrtry>
                                            <Cd>SCOR</Cd>
                                        </CdOrPrtry>
                                    </Tp>
                                </CdtrRefInf>
                            </Strd>
                        </RmtInf>
                        <RltdDts>
                            <AccptncDtTm>2021-08-02T00:00:00.000Z</AccptncDtTm>
                        </RltdDts>
                    </TxDtls>
                </NtryDtls>
            </Ntry>

            <Ntry>
                <NtryRef>1</NtryRef>
                <Amt Ccy="EUR">16376.68</Amt>
                <CdtDbtInd>DBIT</CdtDbtInd>
                <Sts>BOOK</Sts>
                <BookgDt>
                    <Dt>2021-08-10Z</Dt>
                </BookgDt>
                <ValDt>
                    <Dt>2021-08-10Z</Dt>
                </ValDt>
                <AcctSvcrRef>207650</AcctSvcrRef>
                <BkTxCd>
                    <Domn>
                        <Cd>PMNT</Cd>
                        <Fmly>
                            <Cd>RCDT</Cd>
                            <SubFmlyCd>ESCT</SubFmlyCd>
                        </Fmly>
                    </Domn>
                    <Prtry>
                        <Issr>FFFS</Issr>
                    </Prtry>
                </BkTxCd>
                <NtryDtls>
                    <TxDtls>
                        <AmtDtls>
                            <TxAmt>
                                <Amt Ccy="EUR">16376.68</Amt>
                            </TxAmt>
                        </AmtDtls>
                        <BkTxCd>
                            <Domn>
                                <Cd>PMNT</Cd>
                                <Fmly>
                                    <Cd>RCDT</Cd>
                                    <SubFmlyCd>ESCT</SubFmlyCd>
                                </Fmly>
                            </Domn>
                            <Prtry>
                                <Issr>FFFS</Issr>
                            </Prtry>
                        </BkTxCd>
                        <RltdPties>
                            <Cdtr>
                                <Nm>Yritys Oy</Nm> OP Laskulainaa käyttävät yrityksen nimi
                            </Cdtr>
                            <CdtrAcct>
                                <Id>
                                    <IBAN>FI5841000000000000</IBAN>
                                </Id>
                            </CdtrAcct>
                        </RltdPties>
                        <RmtInf>
                            <Strd>
                                <CdtrRefInf>
                                    <Tp>
                                        <CdOrPrtry>
                                            <Cd>SCOR</Cd>
                                        </CdOrPrtry>
                                    </Tp>
                                    <Ref>15240152428</Ref>
                                </CdtrRefInf>
                            </Strd>
                        </RmtInf>
                        <RltdDts>
                            <AccptncDtTm>2021-08-10T00:00:00.000Z</AccptncDtTm>
                        </RltdDts>
                    </TxDtls>
                </NtryDtls>
            </Ntry>

Consumer invoicing and OP Laskulaina

OP can also grant loans against consumer invoices but it is a company specific decision that they do case by case. If you want to send your consumer invoices also through the service, you will need to contact OP’s customer service (asiakaspalvelu@op-laskulaina.fi) to request this feature. Later there will be an API call to do that. If you activate consumer invoice sending, remember to add OP’s IBAN to your bank agreements (SI-message type CHANGE) before starting to use OP’s IBAN in your consumer invoices.

In case consumer invoices are not routed through the service, do not use OP’s IBAN on these invoices.

Payments done directly to company account

In case the receiver pays the invoice using company’s own payment information instead of the OP’s use POST ​/v1​/services​/op_invoice_credit​/direct_payment to inform OP about that. Mark the invoice to be directly paid to the sender instead of the OP’ account by giving the invoice id (uuid) in the API call.

OP Laskulaina Q&As

Q: Company has sent an invoice for 10 000 € and withdrawn a loan of 8000 €. After this they realize that they need to credit the sent invoice. What happens?
A: Next invoices that are sent and paid with OP’s account information will be used for the loan repayment. If no new invoices are sent, the withdrawn loan will accumulate the interest. Company might want to contact OP and agree on some other repayment manner.

Closing the OP invoice credit service

The service can be closed only when there is no withdrawn loan left unpaid. If there is still some interest left OP will collect those directly from the company. API for closing the service is not yet available. Contact our support if you wish to close the service.