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. As an additional electronic route we also support sending to digital mail service Kivra and through our print service route, there is a possibility to forwards invoices and letters to consumer’s digital mail box, OmaPosti. Below is the list of all the options that are available for sending invoices to consumers:

e-invoices to netbank
Direct debit
Kivra digital mail service
Email
Print
OmaPosti

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 and direct debit 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.
• Credit Note and Cancellation Invoice are also supported. For Finvoice it is InvoiceTypeCode INV02 and total sum must be always a negative.

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>

Kivra

Kivra is a digital mail service that allows consumers to receive invoices, letters, and various documents in an electronic format. To learn more about Kivra, visit their website at https://kivra.fi/.
Companies can utilize Kivra through Maventa to send invoices to consumers. Also, consumers have the option to make payments for the invoices through the service.

Kivra functions as one of the electronic routes (relay) in our automated routing, positioned after e-invoice and before email routes. If an invoice is sent without the consumer’s full e-invoice address (IBAN and bank operator), lookup towards Kivra’s consumer registry is performed based on the data on the invoice. If a consumer has a Kivra account, and hasn’t blocked invoices from the sender in question (based on the sender’s bid), invoice is delivered to their Kivra account. In case the Kivra route fails, the invoice is routed via the next available route, such as email or print.

Lookup towards Kivra’s consumer registry is done using the following information from the XML:

1. Email (email verification is done by consumer when Kivra account is created)
2. Full name + street address + postal code + post office (Kivra takes consumers address details from the official address registry)
3. Full name + phone number

Note! If the invoice is forced to the email or print routes, the Kivra route is bypassed. Kivra functions as an e-invoice (relay) route and the activation of the e-invoice route is a prerequisite for enabling Kivra sending. If the sender wants to deactivate Kivra sending, this can be done by disabling the e-invoice route (relay). There is no dedicated setting or parameter specifically designed to disable Kivra alone.

OmaPosti

OmaPosti is an application that allows consumers to receive their letters electronically instead of in a paper form. In case a consumer invoice is going to print, our print service provider will do a look up towards the OmaPosti consumer registry. When a consumer has an active OmaPosti account and has not opted out of receiving digital letters from a sender in question (based on the Maventa account’s OVT code), the invoice will be redirected to the consumer’s OmaPosti account instead of being delivered as a paper document. However, if the consumer does not have an OmaPosti account, the invoice will be printed and sent as a paper letter to the consumer.

To determine if a consumer has an OmaPosti account, a combination of their name and postal address or social security number is used for identification. It is good to keep in mind that while a social security number (ssn) can be used as an identifier, it is highly recommended not to include such sensitive information on invoices.

It is also possible for the sender to exclude an invoice from being sent through the OmaPosti route by setting a parameter print_settings[prevent_digital_post] to “true” while using POST ​/v1​/invoices to send or setting the parameter prevent_digital_post to “true” while using the invoice_put_invoice_with_metadata method for sending.

In summary, OmaPosti provides a digital alternative for receiving letters and in Maventa OmaPosti works only through the print route. Specific criteria mentioned above are used to determine whether an invoice should be sent electronically or as a physical document.

Consumer invoicing in Norway (B2CNO)

Invoices can be sent through Maventa to consumers via direct debit (AvtaleGiro), netbank and Vipps (eFaktura), Digital postkasse innbygger (DPI, only for municipalities), e-mail and print. The invoice can be forced to go to a specific route like eFaktura or it can be specified to try all routes in a predefined order to reach the consumer with the help of our routing logic. Activation comes at no cost, and there are no extra monthly or yearly charges associated with using the service. Your only expense will be for the transactions you make.

Updates regarding the consumer invoicing in Norway:

• eFaktura means both sending to Netbank and Vipps as long as the consumer is part of the “Yes to all” registry (JTTA) and has not disabled receiving in their Vipps application. What is sent to netbank is also shown in the Vipps application. Invoice is visible, and it can be paid in both netbank or Vipps, but cannot be paid twice. It is not possible anymore to only receive in Vipps.
• eFaktura 1.0 with efaktura references are being phased out to be replaced completely by the JTTA: 1. It is no longer possible to create new references in the bank.
  2. Agreement capture (Avtalefangst) no longer works, and API method returns error.
  3. Existing references are used as a lookup towards JTTA to find efaktura identifier. This is kept alive to cover when someone receives invoices on behalf of another person since this is not covered by JTTA.
  4. We no longer send out consumer request to create references.
• Nets has been taken over by Mastercard Payment Solution. Nets no longer exists and Mastercard is referred to as MPS.

  Activation and agreements

There are two vendor agreements that needs to be signed in order to use both the direct debit and eFaktura (netbank and Vipps) routes.

• The main vendor agreement - For eFaktura (and Vipps) and fallback routes e-mail and print.
• The direct debit agreement - For direct debit (AvtaleGiro)

The main vendor agreement

Before the company can send consumer invoices through Maventa, or enable any of the extra features like the direct debit solution, the main vendor agreement must be activated. The main vendor agreement enables the sending of eFaktura (netbank and Vipps) and using the fallback routes e-mail and print. To enter into an agreement with Visma is enough to reach all the banks and the company does not need a separate agreement with their own bank to enable the consumer invoicing.

Only a norwegian company account in Maventa can activate the agreement and send invoices to Norwegian consumers.

When activation is initiated either through the API or UI, Maventa does a query to MPS (Mastercard payment services) to check if the given organisation number already has an existing agreement through another service provider. If another agreement exists, the person with signatory rights for the company needs to sign an agreement through Visma Sign’s electronic signing service to give consent for Visma to move the old agreement and all the existing consumer agreements to Visma. In this way the old agreement with old service provider is closed. Maventa imports all the existing consumer agreements the company might already have and they are stored in Maventa Consumer Vendor Registry (CVR). The existing e-invoice reference will automatically entered into the customer number field in the CVR.

If the company does not have existing consumer agreement, the service is activated immidiately without the need to sign a separate agreement through Visma Sign as the company has already approved the Visma TOS.

Activation timeline: MPS creates the agreement immediately but it usually takes about an hour for the information to get updated on Maventa as we fetch new agreements every 30 minutes. For the agreement to get activated within all the banks, it can take up to 24 hours since each bank fetches agreements from MPS under different timelines. Usually it only takes a couple of hours.

API methods for activating the main vendor agreement:

b2c_issuer_agreement_order

Agreement for B2CNO

Consumer vendor registry and eFaktura reference

The consumer vendor registry (CVR) stores all the consumer agreements, the consumer’s eFaktura references. A consumer’s eFaktura reference is what identifies the consumer with the supplier, and it works as a connection between the consumer and their invoices. Vendor registry has been the central role in transporting consumer invoices between the supplier and the consumer as eFaktura but now the “Yes to all” registry (JTTA) is about to replace the unique agreements.

NOTE! It is no longer possible to create new eFaktura references. The consumer vendor registry will at some point be deprecated and deleted. Existing efaktura references are only used as keys towards the JTTA.

Update: AutoInvoice will check against CVR first. If there is an active agreement in CVR then that will be used to send the invoice. If there is not an active entry in CVR then AutoInvoice will check torwads the Y2A registry.

Yes to All registry (JTTA) and eFaktura identifier

“Yes to All” registry or “Ja takk til alle” registry (JTTA) is a way for consumers to accept e-invoice from all the suppliers. When doing this the consumer gets added into a MPS registry and gets assigned an eFaktura identifier which is then the same identifier used by all the supplier when sending e-invoices to that particular consumers in their netbank. With an eFaktura reference (CVR) there is a direct connection between the specific supplier and the consumer, but an eFaktura identifier is more general that all suppliers can use. By activating the “Yes to All” from their netbank, consumer accepts e-invoices from all suppliers that are able to send e-invoice. When “Yes to All” is activated there is no need for the supplier to send out any consumer requests and the first invoice can be sent directly to the consumer’s netbank.

Maventa does not fetch and store the eFaktura Identifiers, but instead uses the Yes to All registry for lookup to get the consumer’s eFaktura identifier based on the data given on the invoice including email, phone, address, name and SSN. Order and combination of the data used:

1. Social security number (SSN)
2. Date of Birth + Phone number + email combination
3. If one or two of the above is missing (DOB, phone number or email) then name, postalcode and city is used. If there is no DOB, phone number nor email given, there will be no lookup towards Yes to All registry and invoice will be routed to next possible channel

Note! Not all banks are onboarded to Yes to All registry and the banks that are onboarded do not push all the aliases to the registry. MPS is continuously working on getting more banks onboarded and improving the process.

Direct debit agreement for AvtaleGiro

AvtaleGiro is a direct debit payment method used throughout Norway

Direct debit solution through Maventa means that when the direct debit invoice is sent, the deduction file is created automatically by MPS based on the data from the invoice. By using Maventa solution the supplier does not need to create the deduction file themselves and then sent it through another channel as the direct debit has worked before. So this solution handles BOTH the deduction file and the invoice notification.

Through Maventa it is possible to send an invoice and Maventa will route it is a direct debit invoice to MPS 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 MPS.

Mandates will be collected and stored in AutoInvoice.

NOTE! This is not to be confused with a current combo solution thorough AutoInvoice where the invoice notification is sent through us BUT the deduction file must be created elsewhere and sent to MPS either through direct integration or through AutoPay.

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. customer ID = 229221 in the agreement. This is to identify that company gives authority to AutoInvoice to send deductions files on behalf of the supplier, and to fetch mandates.

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 MPS.

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

Maventa 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 Maventa 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 MPS. However, the mandates can only be fetched from MPS by Visma.

Agreement can be activated through the API or UI.

Mandates

Once the general AvtaleGiro agreement is in place, a payer can create one or more payment mandates, each of which is an agreement between the payer and the payer’s bank to automatically pay recurring bills to a specific payee on the due date. Mandates can only be registered in connection with payees that offer AvtaleGiro. Mandates include the following information:

​KID – identifies the payer/payee relationship
Payer’s account number
Payee’s account number
Amount limit – the maximum amount per month which will be automatically paid to the specific payee connected to the mandate. This limit is set by the payer and is considered private information; it is not shared with the payee
Notification setting – The payer specifies if they would like to be notified each time a new payment is scheduled

Payment mandates can be initiated in several ways:

​The payer can register a mandate in their online bank using suggestions from the bank which are based on historic payments
The payer can use Mastercard Payment Services’ suggestions at https://pvu.nets.no/pvu-suggestions/avtalegiro. Suggestions are based on historic payments and are not available for all banks
If the payee offers Mastercard Payment Services' E-Agreement service, the payee can send the payer to Mastercard Payment Services’ web-based onboarding solution. This solution requires the payer to authenticate using BankID, and is generally linked from the “my account” area of the payee’s website
A paper or PDF coupon which is provided by the payee can be filled out by the payer and returned. The payee will then forward the slip to Mastercard Payment Services for processing, either by regular post or electronically via SFTP. Paper/PDF coupons have the following requirements:
    KID
    Payee name
    Payee account number
    Payer account number
    Amount limit
    Notification preference (yes/no)
    Must be in portrait layout with all information on one page​

Mandates are created by the consumer either through the suppliers webpage, or supplier sends out papers to be filled in, or the consumer can create it in their nettbank after they payed the first invoice.

Note! As long as the consumer has an active mandate and e-invoice agreement, the invoice will always be the notification.

Mandates are shown in EUI and can be fetched through the API.

We fetch the mandates when avtalegiro is actived and then we updated mandates 4 times a day (poll for new ones, updated ones)

kid string account_number string notification boolean 1 - consumer wants to be notified of avtalegiro sends, 0 - consumer does not want notification status integer 1 - active, 0 - inactive updated_timestamp string

Sending consumer invoices

Sending an invoice as direct debit (AvtaleGiro)

When the main vendor agreement and direct debit agreement are both active, direct debit invoices can be sent.

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

Prerequisites

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

Notification on upcoming Direct Debit

It is the consumer’s 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 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 Maventa only sends the invoice as a direct debit without notification.

It is possible to disable notifications if the suppliers chooses to.

Notification via eFaktura

If the consumer has eFaktura activated, through “Yes to All” 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. Maventa 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.

Routing

The direct debit route, netbank_agiro will be added to our default route order as a first choice or it can be forced by specifying netbank_agiro in metadata. The invoice will be passed towards MPS if the above prerequisites are there, otherwise it will be routed to the next route which is netbank as en e-invoice.

Currently this is not on the default route. It must be added manually. When added manually then the invoice will be checked towards ATG first.

ATG and e-invoice agreement active
Is there a KID, bankaccount and due date (3 days due date). Basic validation check (sum etc)
Is there an active mandate
Is there an e-invoice reference/Y2A. If not then notification goes to e-mail/print. 
Send or next route. 
If MPS returns an error that the mandate is not active then we go to next route. 

EINVOICE_AGIRO - Cost 3 NOK - Only one avtalegiro transaction, no notification is sent. EINVOICE_AGIRO_EMAIL - free - One avtalegiro transaction (EINVOICE_AGIRO) and e-mail is sent for notification EINVOICE_AGIRO_PRINT - Cost 9.50 NOK without cover sheet - One avtalegiro transaction (EINVOICE_AGIRO) and the notification was sent to print. EINVOICE_AGIRO_PRINT_EXTRA_PAGE - Cost .50 NOK cost for coversheet EINVOICE_AGIRO_COMBO - Cost 3 NOK - One transaction for Avtalegiro deduction and efaktura as notification.

Sending an invoice as eFaktura to MPS

When the main vendor agreement is active the first invoice can be sent. If the sender’s old agreement has been moved over to Visma from another service provider, the existing efaktura consumer agreements are fetched to Maventa in the activation process. In order to send an invoice as eFaktura the receiver must be registered in in the “Yes to all” registry with MPS (JTTA) or have a consumer agreement directly with the sender.

validation on eFaktura:

Due date validation. Has to be minimum three days before due date.
Payable amount must be postive amount.
Bank account is validated 11 digits and MOD 11.
KID validation 2-25 digits MOD 10 check. 

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:

Default route, preferred route

It is recommended that new integrators use the route_order to send consumer invoices

Recipient_type = consumer identifies the invocie as going to B2C route. If “consumer” is not specified then the invoice will go to the B2B route. Route_order specifies the available routes and priorities of those route. If the route_order is empty then the invocie will go the predefined default B2C order

For suppliers that does not really think about how the invoice was distributed they can leave out route_order completely, as long as receipient_type is equal to “consumer”, and that will trigger the invocie to go into a default route order:

netbank (e-invoice to online bank (eFaktura to Nettbank) 
e-mail
Print 

The supplier has a choice of specifying their preferred route in the metadata by using route_order. This will determine all the routes that AutoInvoice will send the invoice to, and also in a prioritzed order.

Example of sending the invoice to a defined route order:

{ “version”:”1.1”, “recipient_type”: “consumer”, “routing”: { “route_order”:[“vipps”, “email”, “print”] } }

Invoice is sent to print only if print is specified in route_order.

Print does not have to be enabled in settings. 
Printed invoice will always use the senders invoice_image, regardless if the "use own pdf" is enabled in settings.

It is possible for AutoInvoice to change the default route order per company if there is a real need for this, for example that a company does not want to use e-mails to send their invoices.

Please contact AutoInvoice team for more information.

This will work like this:

If recipient type = consumer and there is route_order spcified on that company, the invoice will be routed accordingly.
If recipient type = consumer, and no_route order is set, but something is set in settings table, the invoice will be routed accoring to settings table.
If recipient type = consumer and no route_order and nothing in settings table, the invocie will be routed according to the default value.

Send an invoice as eFaktura to Vipps

Maventa 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 MPS 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 MPS, 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. Maventa 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 Maventa 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)

Maventa 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 Maventa team.

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

Sending to MPS

…

Consumer invoicing in Sweden (B2CSE)

Invoices to consumers can be sent through Maventa as e-invoices to the consumer’s netbank, Kivra or via email and print. Distribution is handled by our partner, Compello.
In Sweden also companies can receives invoices through this channel as a company can have an SSN (social security number) as their organization number.

B2CSE solution is currently under piloting. Integration details will be added later. If you are interested in hearing more about our B2CSE solution, please contact us through support@maventa.com.

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 0216)
• Sweden - Organisation number (prefix 0007)
• Denmark - CVR (prefix 0184)
• Netherlands - KVK or VAT number (prefix 0106 or 9944 - depending which is used to register company account to Maventa)
• Belgium - organisation number CBE (prefix 0208)

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 a webhook. 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 the invoice is not possible to send as an e-invoice or email invoice.

The requirements to send the invoice by print are that:

• The sender company needs to have the print service activated
• The full postal address of the receiver 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.

Activating the printing service

To be able to use the print as a delivery option for the invoices, the printing service needs to be activated separately for a company account. Activation can be done through the API or UI.

Template

Invoices sent via print service will by default use Maventa generated invoice image template. This template is optimized for effective handling and it fits perfectly to the envelope used by the printing service provider. Customers can customize the template by adding their company logo to the invoice template (via UI or API).

Examples of Maventa templates here.

There is also an option to use the customer’s own invoice image for all the prints or per invoice (via UI or API). A cover sheet with address details will be added by Maventa to all printed invoices with the customer’s own image enabled and the cover sheet is debited as an extra page. The reason for the cover sheet is to make sure that the address details fits to the envelope.

Prints are always double-sided if there is more than one page.

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

See below for country-specific configuration options and requirements:

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
• One iPost-XML should only have reference to one PDF letter (iPost-XML to PDF 1-1 ration)
• 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 7 sheets in the printed document. When document has more than 7 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 14 pages on an document for it to be more than 7 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="Your company Oy" contact="" contactPerson="Support" email="support@support.com" phoneNumber="010-5058474" ovtID="003712345678">
        <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.

OmaPosti delivery

OmaPosti is an application that allows customers to receive their letters electronically instead of in paper form. When a receiver has an active OmaPosti account and has not opted out of receiving digital letters from a specific sender (based on the sender’s ovtID given in the IPOSTXML), the invoice will be redirected to the receiver’s OmaPosti account instead of being delivered as a paper document. However, if the receiver does not have an OmaPosti account, the invoice will be printed and sent as a paper letter to the recipient. To determine if a receiver has an OmaPosti account, a combination of their name and postal address is used for identification.
It is also possible for the sender to exclude the letter from being sent through the OmaPosti route by setting the prevent_digital_post parameter to true in the sending API call.

Please note that in order for the OmaPosti route to function correctly, the necessary information must be specified in the IPOSTXML document. This includes the sender’s OVT code (ovtID) and the receiver’s name and address information.

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

• API to modify Receivables settings (contact person information etc.)

Receivables Management process flow

Step by step default 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 an invoice ends up in the error state, Visma Financial Solutions is notified. In case the sender does not act on the error, and the invoice remains in error state even when the invoice is due, Visma Financial Solutions closes the assignment and adds a comment about the closing reason to the assignment details.

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). Language of the reminders and debt collection letters is based on the customer’s language code defined in the original invoice (Finvoice InvoiceRecipientLanguageCode). Default language is Finnish.

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. This happens usually within 1-2 workdays. 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 request 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

Use of own invoice image and payment details

There is also a possibility for senders to use their own invoice image and payment details on the invoices sent through the Receivables service. When this setting is enabled payment details in invoices will not be modified by Visma Financial Solutions and Maventa will not drop the original invoice image and create a new one as it would happen in the default process of how the service normally works.

When a company’s own payment details are used on invoices, receivers will pay the invoice directly to the company’s own account. Therefore all the payments need to be informed to Visma Financial Solutions as direct payments for them to be able to update the assignments accordingly (mark assignment as paid and closed). This means that in order to use this setting the company’s ERP needs to have the full Receivables integration including an automated process for informing direct payments through the API (See Handling payments under the events).

In the service activation there is a parameter called accountable_party which defines who is the receiver for the payments. By default the value is set as “vfsfi” which means that Visma Financial Solutions Oy is the one receiving the payments. This is the default process where invoice details are modified by the service. If accountable_party is left empty or not defined at all, the default value is used. By setting the accountable_party as “company”, invoices are sent to the receivers with the sender’s own payment details and invoice image. Sender will be the receiver of the payments and payments must be informed as direct payments to Visma Financial Solutions Oy through the Receivables API.
Use of own invoice image and payment details can also be enabled afterwards using a PATCH /v1/services/receivables endpoint by setting the accountable_party to company”.

As it is crucial to report all the payments (expect the ones coming from a payer that name starts with VISMA FINANC) as direct payment through the API, the use of the above mentioned parameter is only allowed for predefined ERPs (vendor keys) that have been verified to have a proper automated solution for handling the direct payments through the API. If you as an integrator wish to use this setting, please contact our support team (support@maventa.com) to verify your integration and to add your key as allowed one. Also note when handling the payments all the payments where payer’s name is starting with “VISMA FINANC” should not be reported as direct payments as they are reminder or payment demand payments and Visma Financial Solutions will in these cases mark the assignment as paid/partially paid.

How to change company information

If you want to change company information, you will need to contact our support. Currently it is not possible to do via the API.

Service levels for customers

If there is a need to limit the debt collection of a certain customer (company), that can be done by adding the customer to a VIP or PREMIUM customer group. Please note that the default model is the most effective option in terms of cash flow and does not require any actions from the user. Adding customers to the service level groups will tranfer the responsibility for monitoring the assignment, preventing expiration of the assignment etc. to the user. In some cases using service level groups might create additional costs for the sender. The grouping feature works based on the customer’s business ID - please make sure that the customer’s information has the correct business ID and that the ID is also given corrently on the invoice XML when sending. If you have added the customer to a group, but you decide you want to continue collecting invoices - simply remove the customer’s business ID from the customer group listing.
Please note that the debt collection does not continue on cases that have been closed in the process earlier even if the customer group is updated.

Service level can be set using the PATCH ​/v1​/service_levels​/{customer_bid}

On assignment there is a parameter called service_level. In case the customer in question is either on the PREMIUM or VIP service level group, that parameter will return the information accordingly. If customer is not on the VIP or the PREMIUM group, the parameter will be “default”. There will also be an event added for the assignment, called service_level_changed that will indicate the service level if it is either VIP or PREMIUM. Note! service_level information does not get updated immediately after the invoice is sent and assignment is created. It will get updated after a few hours from the sent.

DEFAULT customers

The default payment monitoring process is pictured below. This is the most effective option in terms of your cash flow and requires no action from you.

PREMIUM customers

A payment reminder and a demand for payment are sent for an overdue invoice, after which the collection of the invoice ends 30 days after the due date of the demand for payment. After this, the responsibility for monitoring the receivable, preventing expiration of the receivable etc. is transferred to your own responsibility. If the customer has not paid the open receivable in full, you will be charged 30€+VAT.

VIP customers

Only a payment reminder will be sent for an overdue invoice. The payment reminder has no reminder fee for your customer. The collection of the invoice ends 30 days after the due date of the payment reminder and the case will be closed. After this, the responsibility for monitoring the receivable, preventing expiration of the receivable etc. is transferred to your own responsibility. You will be charged 5€+VAT for each payment reminder sent

No payment monitoring

If you do not want to transfer a specific customer’s invoices to Receivables management service payment monitoring at all, add the customer’s business ID below. The information on these invoices will not be transferred to Visma Financial Solutions Oy. Please note that your own account number will be printed on these invoices and you must take care of the processing of the payments, the control of the receivables, preventing expiration of the receivable etc. yourself. There are no additional costs for you.

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 assignment. On the other words the invoice hasn’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 is 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",
    "collection_status": "unknown",
    "service_level": "default",
    "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",
    "partially_closed_at": null,
    "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.

Possibility to create assignment manually (without sending invoice to the recipient)

There is a possibility to create assignments manually for the Receivables service without sending an actual invoice to the receiver through Maventa.

This functionality comes especially handy for housing companies that usually send one invoice at the beginning of the year containing all the upcoming payments for that particular year for all their customers. And in order to follow up the monthly payments, they can create assignments for the service each month. In this way the Receivables service can take care of the payment monitoring and start reminder and collection processes automatically in case the due date has passed.

Adding assignments manually can be done with the POST ​/v1​/invoices by setting the prevent_routing parameter to true. Setting the parameter true will mark the invoice immediately as SENT state without actually sending it anywhere, and creates an assignment to the Receivables service to be followed up as any other assignment.

For the call you will need a valid invoice XML with all the needed data including full receiver’s address details and due date that is in the future. The use of the prevent_routing parameter is only allowed for predefined ERPs (vendor keys). If you as an integrator wish to use this setting, please contact our support team (support@maventa.com) to verify your integration and to add your key as allowed one.

Note! remember to inform the payments for these manually created assginments as direct payments so that Visma Financial Solutions is up to date when the original invoice gets paid.

Creating assignments manually will have a debit action and it will be billed according to the existing price lists.

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"
    }
  }

  {
    "type": "freeze_confirmed",
    "data": {
      "happened_at": "2019-01-04",
      "end_date": "2019-02-15"
    }
  }

  {
    "type": "unfreezed",
    "data": {
      "happened_at": "2019-01-04"
    }
  }

Other events

Messaging functionality

Messaging functionality is used for the communication between Visma Financial Solutions and the customer. Customer can add a comment or question related to the assignments or Visma Financial Solutions can contact customer regarding some important information related to the assignments. It is highly recommended to add this functionality as part of the integration to make sure both parties have a functional discussion connection and important messages do not get lost.

API endpoints for messaging functionality

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 and customize by any integrator. For more information about our EUI and how to take that into use can be found here

Dasboard of the receivables. You can show the whole EUI with the main top navigation bar (this way customers can access other parts of the EUI as well):

Listing of open assignments. You can also hide the main menu and only show the Receivables part of the EUI:

Details of one assignment. You can only show the details of only one assignment. This view could be part of the sent invoice details inside the ERP by 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

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. Company must complete the customer authentication process to enable the receiving of invoices. 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.

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 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

Sweden

Scan service identifies the recipient using the FeAddress (Postal scan address) and company name on the envelope

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. 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.

Visma Scanner and DocScan

Maventa has integration to Visma Scanner and DocScan scan applications. Visma Scanner is a mobile application for scanning and DocScan is a web application (Visma Home). Both applications can be used to forward invoices and vouchers and to get data interpreted from them into an accounting system.

Scanning is based on machines only, which means both products use machine learning based technology (SmartScan) for interpreting the data. Benefits of using Visma Scanner and DocScan are easy and quick usage combined with lower cost.

Visma Scanner and DocScan can be integrated directly to ERPs or accounting systems or the integration can work through Maventa.

What is needed for enabling Visma Scanner or DocScan integration

Receiver company needs to have Maventa account and receiving activated. Sender needs to have Visma Scanner mobile app or use DocScan web app (from Visma Home).

Invoices delivered via Visma Scanner or DocScan can be downloaded as part of the regular invoice receiving flow. If receiver wishes to receive vouchers as well, it’s requered to register a separate network SCAN_DOCUMENTS with profile VOUCHER. In addition, accounting system needs to be able to download vouchers via Document Exchange and handle the voucher xml.

Latest version

You can find and download the installer and more information about the latest version here

Please also note that Connector version 2.0+ requires .NET Framework 4.6.1.

Old versions

We do not recommend using old versions of Maventa Connector. For special cases we keep some old versions available. Please contact our support for more information.

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.

Header image to customize email

Invoice email body can be customized by adding a header image that will be visualized on top of the email. Adding a header image to customize the email provides a great opportunity to enhance recognition and ensure that recipients can easily identify the sender.

Header image can be added via API using the endpoint PATCH /v1/company/settings by updating the company settings with the chosen image, or via the UI from invoice settings.

• Only PNG is allowed image format
• We recommend a width of around 650 pixels to 700 pixels, along with a height between 90 pixels to 200 pixels

Once the email header image is added, the next time an invoice is sent via email, the email will feature the uploaded image. It is important to note that the header image only affects the invoice email. Other types of emails, such as notifications, will not include the header image.

Payment links

There is a possibility to add customer’s own payment link to be visible on the email invoice display service. This will enable the recipient to access the payment service by simply clicking the provided payment link within the email invoice display. To ensure security, we require prior approval of the link’s domain, and we always validate the link before displaying it. If you wish to use payment links in your invoice emails, please reach out to our support team at support@maventa.com to request the activation of this feature.

Link can be given in an AdditionalDocumentReference element in UBL based formats (PeppolBIS 3.0, SiUBL 2.0) by defining the ID as “68” and DocumentDescription as “Payment link”. Link itself is given in the URI field.

Message to the email receiver

Sender can define a message and contact details that are shown in the email body. These details can be added 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.