Integration guide

Consumer invoicing in Finland

Invoices to consumers can be sent through Maventa via email, print or then as an e-invoices or direct payments to the consumer’s netbank. 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.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:eb="http://www.oasis-open.org/committees/ebxml-msg/schema/msg-header-2_0.xsd" xmlns:xlink="http://www.w3.org/1999/xlink">
<SOAP-ENV:Header>
<eb:MessageHeader SOAP-ENV:mustUnderstand="1" eb:id="20200731110324320000" xmlns:eb="http://www.oasis-open.org/committees/ebxml-msg/schema/msg-header-2_0.xsd">
<eb:From>
<eb:PartyId>FI4941452835555555</eb:PartyId>
<eb:Role>Sender</eb:Role>
</eb:From>
<eb:From>
<eb:PartyId>SBANFIHH</eb:PartyId>
<eb:Role>Intermediator</eb:Role>
</eb:From>
<eb:To>
<eb:PartyId>003712345678</eb:PartyId>
<eb:Role>Receiver</eb:Role>
</eb:To>
<eb:To>
<eb:PartyId>DABAFIHH</eb:PartyId>
<eb:Role>Intermediator</eb:Role>
</eb:To>
<eb:CPAId>yoursandmycpa</eb:CPAId>
<eb:ConversationId>nnnn</eb:ConversationId>
<eb:Service>Routing</eb:Service>
<eb:Action>ProcessReceiver</eb:Action>
<eb:MessageData>
<eb:MessageId>2020083111032432000022</eb:MessageId>
<eb:Timestamp>2023-09-31T11:03:24+03</eb:Timestamp>
<eb:RefToMessageId>20150609223129270000</eb:RefToMessageId>
</eb:MessageData>
</eb:MessageHeader>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<eb:Manifest eb:id="Manifest" eb:version="2.0">
<eb:Reference eb:id="Finvoice" xlink:href="20200731110324320000">
<eb:schema eb:location="http://www.pankkiyhdistys.fi/verkkolasku/finvoice/finvo" eb:version="2.0"/>
</eb:Reference>
</eb:Manifest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<?xml version="1.0" encoding="ISO-8859-15"?>
<?xml-stylesheet type="text/xsl" href="FinvoiceReceiverInfo.xsl"?>
<FinvoiceReceiverInfo Version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FinvoiceReceiverInfo.xsd">
<MessageDetails>
<MessageTypeCode>RECEIVERINFO</MessageTypeCode>
<MessageTypeText>VASTAANOTTAJAN ILMOITUS</MessageTypeText>
<MessageActionCode>ADD</MessageActionCode>
<MessageActionCodeIdentifier>00</MessageActionCodeIdentifier>
<MessageDate Format="CCYYMMDD">20200831</MessageDate>
<SenderInfoIdentifier>testi</SenderInfoIdentifier>
</MessageDetails>
<SellerPartyDetails>
<SellerPartyIdentifier>1234567-8</SellerPartyIdentifier>
<SellerOrganisationNames LanguageCode="FI">
<SellerOrganisationName>Your Software Oy</SellerOrganisationName>
</SellerOrganisationNames>
<SellerOrganisationNames LanguageCode="SV">
<SellerOrganisationName>Your Software Oy</SellerOrganisationName>
</SellerOrganisationNames>
<SellerOrganisationNames LanguageCode="EN">
<SellerOrganisationName>Your Software Oy</SellerOrganisationName>
</SellerOrganisationNames>
<SellerOrganisationBankName>Your Software Oy</SellerOrganisationBankName>
<SellerPostalAddressDetails>
<SellerStreetName>Tie 6</SellerStreetName>
<SellerTownName>Helsinki</SellerTownName>
<SellerPostCodeIdentifier>00200</SellerPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>SUOMI</CountryName>
</SellerPostalAddressDetails>
</SellerPartyDetails>
<InvoiceSenderInformationDetails>
<SellerWebaddressText>www.yritys.fi</SellerWebaddressText>
<InvoiceSenderAddress>00372345678</InvoiceSenderAddress>
<InvoiceSenderIntermediatorAddress>DABAFIHH</InvoiceSenderIntermediatorAddress>
</InvoiceSenderInformationDetails>
<SellerAccountDetails>
<SellerAccountID IdentificationSchemeName="IBAN">FI4941452835555555</SellerAccountID>
<SellerBic IdentificationSchemeName="BIC">NDEAFIHH</SellerBic>
</SellerAccountDetails>
<SellerInvoiceDetails>
<PaymentInstructionIdentifier>Lasku</PaymentInstructionIdentifier>
<SellerInstructionFreeText LanguageCode="FI">Syötä yritykseltä saamasi rekisteröintitunnus.</SellerInstructionFreeText>
<SellerInstructionFreeText LanguageCode="SV">Ange registrerings-ID du fått från företaget.</SellerInstructionFreeText>
<SellerInstructionFreeText LanguageCode="EN">Enter the registration ID you received from the company.</SellerInstructionFreeText>
<SellerInvoiceTypeDetails>
<SellerInvoiceTypeText LanguageCode="FI">Liikuntamaksu</SellerInvoiceTypeText>
<SellerInvoiceIdentifierText LanguageCode="FI" SellerInvoiceIdentifierType="99">Rekisteröintitunnus</SellerInvoiceIdentifierText>
</SellerInvoiceTypeDetails>
<SellerInvoiceTypeDetails>
<SellerInvoiceTypeText LanguageCode="SV">Motionsavgift</SellerInvoiceTypeText>
<SellerInvoiceIdentifierText LanguageCode="SV" SellerInvoiceIdentifierType="99">Registeringsnummer</SellerInvoiceIdentifierText>
</SellerInvoiceTypeDetails>
<SellerInvoiceTypeDetails>
<SellerInvoiceTypeText LanguageCode="EN">Exercise fee</SellerInvoiceTypeText>
<SellerInvoiceIdentifierText LanguageCode="EN" SellerInvoiceIdentifierType="99">Registration ID</SellerInvoiceIdentifierText>
</SellerInvoiceTypeDetails>
</SellerInvoiceDetails>
<ReceiverInfoTimeStamp>2023-09-19T11:03:24+03</ReceiverInfoTimeStamp>
<BuyerPartyDetails>
<BuyerOrganisationName>Matti Mallikas</BuyerOrganisationName>
<BuyerPostalAddressDetails>
<BuyerStreetName>katu 1</BuyerStreetName>
<BuyerTownName>PORVOO</BuyerTownName>
<BuyerPostCodeIdentifier>06100</BuyerPostCodeIdentifier>
<CountryCode>FI</CountryCode>
<CountryName>SUOMI</CountryName>
</BuyerPostalAddressDetails>
</BuyerPartyDetails>
<InvoiceRecipientDetails>
<InvoiceRecipientAddress>FI4941452835555555</InvoiceRecipientAddress>
<InvoiceRecipientIntermediatorAddress>SBANFIHH</InvoiceRecipientIntermediatorAddress>
<SellerInvoiceIdentifier>123456</SellerInvoiceIdentifier>
<InvoiceRecipientLanguageCode>FI</InvoiceRecipientLanguageCode>
</InvoiceRecipientDetails>
<BuyerServiceCode>00</BuyerServiceCode>
<ConversionDetails/>
</FinvoiceReceiverInfo>

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
• For the direct payment, Maventa does not automatically send notifications. Remember to handle the possible notifications yourself. 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 were phased out on 18th of March 2024 and replaced completely by the JTTA: 1. The creation of new eFaktura references has been discontinued already a few years ago
  2. Agreement capture (Avtalefangst) no longer works, and API method returns error.
  3. The “Yes to All” registry or “Ja takk til alle” registry (JTTA) lookup will no longer be performed using the eFaktura reference but will instead rely on the information provided on the invoice (or in the metadata given in sending API).
  4. Automatic import of existing CV-links during the activation process is discontinued.
• 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 to Visma. Note! It is the company’s responsibility to make sure that the old agreement is closed, so that they do not come into a conflict with this agreement.

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

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 the old, already deprecated eFaktura references (CVR) there was 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

Some ERPs have their own direct API connection to MPS to do the JTTA lookup to get the eFaktura identifier and then use that when sending invoices to Maventa.

Direct debit agreement for AvtaleGiro

AvtaleGiro is a direct debit payment method used throughout the 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. Addition to the automatic creation of the deduction file, our solution also handles the invoice notification.

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

To get started the with the AvtaleGiro the supplier needs a direct debit agreement with their bank. This is a manual process today and it is handled outside of Visma. In the agreement with the bank the supplier must specify customer ID as 229221. This is to identify the direct debit solution with Visma and to give consent for Maventa to have an authority to send deduction files on the behalf of the supplier, and to fetch their mandates.

If the supplier already has an active AvtaleGiro agreement with another service provider, they need to authorize the take-over process using Visma sign. During activation the supplier is required to enter an e-mail address to a person within the company that has signatory rights. Once the agreement is signed the activation itself starts and we send the necessary data to MPS.

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 to Visma. Company is responsible for making sure the old agreement is closed. Note! If the supplier already has an active agreement and are already sending deduction files through another service provider, 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.

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)

Agreement can be activated through the API or UI.

Mandates

Mandates will be collected and stored in Maventa.

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

When a consumer creates a direct debit mandate in their bank, they choose if they want to get a notification on a coming direct debit action. They choose if that is enabled or disabled, not how to be notified. We do not support bank notification. We support eFaktura as first choice, then e-mail and print. eFaktura as notification we also need to find them in Y2A (later slides). eFaktura as notification is not possible to pay in bank, unless manually changing it.

Sending consumer invoices

Route order and recipient type

When sending consumers invoices it is mandatory to specify the recipient_type as “consumer” on the sending API metadata. Recipient_type identifies that the invoice is going to the B2C route. If “consumer” is not specified, the invoice will go to the B2B route.

It is also recommended that integrators use the route_order when sending consumer invoices. Route_order specifies the available routes the supplier wants to use and the priority of those routes. If the route_order is empty or it is left out completely the invoice will go to the predefined default route order.

Default route order is the following:

Example of sending a consumer invoice to a defined route order:

{
{ "version":"1.1", "recipient_type": "consumer", "routing": { "route_order":["netbank", "email", "print"] } }
}

When sending B2C invoices, the print service doesn’t need to be enabled in the supplier’s Maventa account. The print route is automatically enabled if it’s specified in the route order or if the default route order settings are used. The printed invoice will always use the sender’s invoice image, if provided, regardless of the print settings.

In certain situations, companies may have a specific need to have the route order set per supplier account not per invoice. In such cases, Maventa can assist in making this change. Please reach out to the Maventa support for further information and guidance on how to proceed with this request.

Attachments and invoice image

Attachments are supported through Visma Document Hotel. Limitations are the same as for print. Maventa send a link to Visma Document Hotel where we show only PDFs. If the invoice contains other attachment formats like .png we do not pass these on to consumer.

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 supplier creating the deduction file and sending it to MPS themselves, the supplier can send the invoice via Maventa and the deduction file is created automatically based on that data on the 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.

Prerequisites for the supplier:

• An active main vendor agreement with Maventa
• An active direct debit (AvtaleGiro) agreement with their bank, with customer ID 229221
• Direct debit activation completed through Maventa

Prerequisites for the consumer:

• An active direct debit agreement with the supplier (a mandate must exist)

The direct debit route is the first option in our default route order if the supplier has the direct debit activated.

Prerequisites towards the direct debit invoice:

• The KID and bank account number are given
• Due date is not in the past and there is at least 3 days until the due date
• Invoice is a valid xml (sum etc)
• There is an active mandate for the consumer

If above mentioned prerequisites are not met or MPS returns an error that the mandate is not active, invoice will go to the next possible route (eFaktura, or email/print).

Consumer notification on upcoming Direct Debit

Consumers have the option to receive notifications about upcoming direct debits when they enter into a direct debit agreement with their supplier. The notification will primarily be sent as an eFaktura if the consumer has activated eFaktura through JTTA. If eFaktura is not activated, the notification can be sent via email or in print. If the consumer does not want to receive notifications, Maventa will only send the invoice as a direct debit without notification.

It is also possible for the supplier to disable notifications if they choose to do so.

Notification via eFaktura

If the consumer has eFaktura activated through JTTA 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 email

If the consumer wants to be notified, and does not have eFaktura active, then the notification will be sent as email 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 paid twice.

Notification via print

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

Sending an invoice as eFaktura to MPS

When the main vendor agreement is active the first invoice can be sent. In order to send an invoice as eFaktura the receiver must be registered in in the “Yes to all” registry with MPS (JTTA).

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. 

API methods:

Send an invoice as eFaktura to Vipps

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.

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.

However the following scenarios need to be taken into account:

1. 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
2. There is no scenario anymore where the invoice is only shown in vipps
3. Creditnotes are not supported in VIPPS. Invoices can be sent to Vipps with total amount = 0.
4. Direct debit invoices are not supported in VIPPS.

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.

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 the Digital Postkasse Innbygger (DPI), which is used only by municipalities (Visma 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 chosen 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 Maventa support.

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 to consumer’s netbank and Kivra is handled by our partner, Compello, and fallback routes, email and print by Maventa.
In Sweden also companies can receives invoices through this channel as a company can have an SSN (social security number) as their organization number.

Activation of the B2C e-invoicing solution

The sender needs to have an agreement with their own bank for consumer invoicing. This agreement is done manually by the sender with their bank. In the agreement they need to specify Compello as a CTD (Certifierad Teknisk Ditributör, Compello is certified as a technical distributor of e-invoices to banks. This means that they act as partners to BGC, Nordea and Swedbank and maintain a secure and high quality service. This certification is renewed once a year).

Once the agreement is signed with the bank the sender gets an FUI (Faktura Utställar Identitet).

The FUI and the following information is needed to activate the service through Maventa. Activation can be done either through our UI or via the API:

• FUI = Faktura Utställar Identitet
• Bank account number (BankGiro or PostGiro number)

Addition to the FUI and account details, Maventa forwards company’s name and business id (bid) to our B2C partner. Note! The sender’s account name in Maventa needs to be the same as in Bolagsverket as that will be checked to be a match.

Our B2C partner then creates connection to the Bankgiro Centralen (BGC), Nordea and Swedbank for the sender to be able to send invoices to consumers’ netbank. Through BGC, Nordea and Swedbank, we can reach all the other banks. Connection to Kivra is created at the same time and will be active once the bank connection is active.

When status for activation is active, the sender can start sending invoices to bank and Kivra. Also an onboarding page is created for the sender, and consumers are able to start listing themselves as receivers in their netbank.

If the sender already has an active FUI and consumer invoicing with another service provider, but wants to use Maventa solution, the FUI and all the FMIs are possible to move to us. This is a manual process, so in this case, please be in contact with our support.

Activation timeline:

There need to be a connection created towards BGC, Nordea and Swedbank and we must receive the status back from all three banks and Kivra before the B2C service is active. This can take up to a week.

Note! In case the sender is also a customer of InExchange, prevent routing all sent invoices through InExchange setting needs to be turned on in order for our B2C solution to work. If the setting is not turned on all sent invoice will be forced through InExchange connection without even trying our B2C route. When the setting is on, Maventa will hande internal traffic, sending to Peppol, email and print routes addition to the B2C and also handles the billing of these actions

Onboarding consumers as receivers of e-invoices and Kivra

Once the B2C service is active, sender is listed as a B2C sender in netbanks, and consumers can create the consumer agreement with them. To make the consumer agreement there is an onboarding page shown in the netbank that consumer needs to fill in. Onboarding page is standardized with Visma logo. If there is a need to customize the page, please be in contact with our support.

Once the consumer agreement is filled in and sent, a unique ID to identify the consumer (FMI - Faktura Mottagar Identitet) is created and is fetched and stored in Compello side. There must be an active FMI for us to be able to send the e-invoice to the consumer’s bank. SSN send on invoice is used to find the FMI for the consumer. To force invoice to consumer’s netbank without an active FMI is not possible through Maventa solution currently.

FMI is a unique ID to identify the consumer. It is stored in compello side, and there is currently no lookup capabilities towards the consumer registry.

FMI is specified as following:

• SSN or organisationsnumber (12 digits)
• Receiver’s bank ID (max 4 digits)
• Country code as SE

Examples from different banks:

• Nordea FMI privatkund: 194001111111.NB.se
• Swedbank FMI privatkund: 194001111111.FSPA.se
• Danske Bank FMI privatkund: 194001111111.OEB.se
• Handelsbanken FMI privatkund: 194001111111.SHB.se

Note! Receiving invoices on behalf of someone else is not supported in our B2C solution currently.

When the BC2SE is activated a connection to Kivra is also created automatically. If there is no FMI found for the consumer’s SSN the invoice will be routed to Kivra if the consumer has Kivra capabilities. To route to Kivra, no agreement between the sender and consumer is needed. lookup towards Kivra’s consumer registry is performed based on the SSN given on the invoice. If a consumer has a Kivra account, 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.

Note! Currently it is not possible to only activate the Kivra without the bank capabilities. If there is a growing need for this, we can re-evaluate the solution.

Sending e-invoice to netbank and Kivra

Before sending invoices through our B2C solutions make sure the service is in active state and that the prevent routing all through InExchange setting is on (read more from activation).

Prerequisite for invoices:

• Invoice must be sent at least three days before the due date on the invoice
• Invoice must have the consumer’s SSN (without the SSN the invoice cannot be routed to netbank or Kivra)
• Credit notes are not supported in our B2C solutions. When credit note is identified, it will skip the BC2 route and will be sent to the receiver either by email or print depending on sender’s fallback settings.

SSN needs to be specified like YYYYMMDDnnnn or YYMMDDnnnn in the endpoint ID field:

<cac:AccountingCustomerParty>
    <cac:Party>
      <cbc:EndpointID schemeID="0007">201012081234</cbc:EndpointID>
      <cac:PartyIdentification>
        <cbc:ID schemeID="0007">201012081234</cbc:ID>
      </cac:PartyIdentification>

How is the invoice routed

When an invoice is sent from the ERP to Maventa, it goes through the following routing logic:

1. Can the invoice be routed internally?
   The value in the endpoint ID (or customer’s business id) field is checked towards our internal capabilities. If we find the receiver, the invoice is sent internally to the receiving party.

2. Can the invoice be routed through Peppol?
   The value in the endpoint ID (or customer’s business id) field is checked towards the Peppol registry. If the receiver is listed in Peppol we route the invoice to Peppol.

3. Can the invoice be routed through Inexchange?
   The value in the endpoint ID (or customer’s business id) field is checked towards Inexchange adressbook. if the receiver is listed as InExchnage receiver we route the invoice to InExchange.

4. If the sender has an active B2CSE service the invoice is routed through Compello
   • Invoice is sent to netbank if the receiver has an active FMI
   • Invoice is sent to Kivra if receiver has an active Kivra account
5. Fallback routes, email and print depending on the sender’s settings and if receiver’s email and address details are given

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 if the company is already registered to receive invoices or other document types 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"
  ],
  "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 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
• When multiple IPost-XMLs in one ZIP file, all IPost-XMLs must have the same printing options (letter class, colour..)
• 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 9 sheets in the printed document. When document has more than 9 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 18 pages on an document for it to be more than 9 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>

Instructions for letter layout

Latest instructions for the letter layout. Addition to Posti as the mail distributor, there is also Jakeluyhtiö Suomi Oy (JYS) which have few additions to the Posti rules. Difference is the tracking barcodes they print on the invoice image, see the JYS rules merged with the Posti ones.

Receiver information should be marked as clearly as possible 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

Storage time

Once the file is successfully sent and we have gotten the final confirmation back from the print service provider, the file is completely remove from Maventa. We recommend storing the files on the ERP side for at least a few months after the sending in case there are some support cases related to the sent letters.

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 Amili (former 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. Service contract and 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 Amili 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 Amili side.
5. Receiver pays the invoice with Visma Amili’s payment information and Visma Amili pays the money to the sender account. When invoice gets fully or partially paid Visma Amili 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 Amili 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 Amili 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

What information on the invoice gets changed

• IBAN - Visma Amili will replace the payment information from the sent invoice with their own IBAN. In this way the receiver pays the invoice using Visma Amili’s account information and then Visma Amili 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 Amili will replace the reference number from the sent invoice with their own one. You will get the reference number used by Visma Amili from the assignment.
• FACTORING CLAUSE is added
• InvoiceFreeText Visma Amili 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 Amili 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. GET /v1/services/receivables method is used to follow up when the service get activated.

To complete the activation process, a person authorized to act on behalf of the company must fill and sign an electronic agreement with Visma Amili. This authorization can be based on the individual’s position within the company or a provided power of attorney, which must be attached to the form if applicable. Personal online banking credentials or a Mobile ID are required to fill out the form. According to the Money Laundering Act, we must ensure that we know our customers and their activities.

The authentication and signing process is facilitated by our partner, Netvisor KYC.

There are two options for handling the Know Your Customer (KYC) part from the ERP:

1. By providing an email address in the “authorization_email” parameter, an email containing a link to the Netvisor KYC service is sent to the specified address. If the “authorization_email” parameter is left empty, no email will be sent

2. The GET /v1/services/receivables method will return a link in “activation_url” parameter to the Netvisor KYC service. Customers can be guided there directly from the ERP. When displaying the link, it is advisable to keep the “authorization_email” parameter blank

Note! If the KYC process is not completed within a week, a reminder email with a link will be sent to the contact person’s email address.

When agreement is signed and verified by Visma Amili 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 Amili 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 Amili 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 Amili 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 Amili 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 with the name VISMA AMILI or part of the name (old 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/is starting with “VISMA AMILI” should not be reported as direct payments as they are reminder or payment demand payments and Visma Amili 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 Amili. 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 Amili 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 Amili. 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 Amili 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 Amili will continue to collect.
3. Closed - The assignment is closed. The assignment has been paid and no charges are open. Visma Amili 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 Amili 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 Amili 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 Amili) 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 Amili 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 Amili 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 Amili 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 Amili and the customer. Customer can add a comment or question related to the assignments or Visma Amili 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.

REST API for message handling.

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 calling DELETE /v1/services/receivables or then by closing the service through the user interface. After the service is closed new invoices sent are not routed through Visma Amili anymore. Visma Amili 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)

Reskontravahti Express enables you to outsource the time-consuming tasks of sending reminders and managing the debt collection process to Visma Amili Oy. The service allows you to choose specific invoices for Visma Amili to handle. By using Reskontravahti Express, you can also monitor the progress of reminder and collection activities through our APIs (and UI).
The service 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. Service contract and price list.

Opening the Reskontravahti Express service

To open the Reskontravahti Express service use REST API method PUT /v1/services/receivables to initiate the activation process. GET /v1/services/receivables method is used to follow up when the service get activated.

To complete the activation process, a person authorized to act on behalf of the company must fill and sign an electronic agreement with Visma Amili. This authorization can be based on the individual’s position within the company or a provided power of attorney, which must be attached to the form if applicable. Personal online banking credentials or a Mobile ID are required to fill out the form. According to the Money Laundering Act, we must ensure that we know our customers and their activities.

The authentication and signing process is facilitated by our partner, Netvisor KYC.

There are two options for handling the Know Your Customer (KYC) part from the ERP:

1. By providing an email address in the “authorization_email” parameter, an email containing a link to the Netvisor KYC service is sent to the specified address. If the “authorization_email” parameter is left empty, no email will be sent

2. The GET /v1/services/receivables method will return a link in “activation_url” parameter to the Netvisor KYC service. Customers can be guided there directly from the ERP. When displaying the link, it is advisable to keep the “authorization_email” parameter blank

Note! If the KYC process is not completed within a week, a reminder email with a link will be sent to the contact person’s email address.

When agreement is signed and verified by Amili the service gets activated. This happens usually within 1-2 workdays.

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

Reskontravahti Express can also be activated through our user interface.

Transferring invoices to a reminder and collection process

Due invoice can be transferred to the Reskontravahti Express service via the following API methods:

Transfer invoice: POST /v1/invoices/{id}/assignment

As an input you will need to provide the invoice id (uuid) for an over due invoice, and the preferred collection type

reminder_and_collection - transfer the invoice to a full reminder and debt collection process
collection - transfer invoice directly to the collection process as you have already handled the reminder sending yourself

Possible errors:

If the due date of the invoice is not in the past, the API returns the following error as only invoices having due date in past can be transferred to the Reskontravahti Express service:

Error: response status is 400

{
  "code": "invalid_parameters",
  "message": "Request parameters are invalid",
  "details": [
    "Invoice not expired"
  ]
}

See the status of the transfer: GET /v1/invoices/{id}/assignment

Pending - Waiting for the transfer
Sent - Transfer successful and an assignment is created. Response will also contain a link to the newly created assignment
Error - Trasfer failed (Most common reason is invalid XML file, or missing receiver’s address details) Note! API does not return the error reason

When invoice due date is in past, a button to transfer invoice to Reskontravahti Express will appear on UI under the sent invoice details.

Possibility to create assignment manually for an invoice not sent through Maventa

There is a possibility to transfer invoices, that have not been sent through Maventa, for the Reskontravahti Express service. This means adding an assignment manually to the service.

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. After the invoice is created, above mentioned Reskontravahti Express APIs can be used to transfer the invoice to the reminder and/or debt collection process.

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

Reminder and debt collection schedule

When invoice is transferred to Reskontravahti Express service for reminder and collection process Visma Amili will send out the first reminder 10 days after the due date of the invoice for B2B invoices, and 14 days after due date for consumer invoices (B2C). In case invoice is transferred directly to the collection process, payment demand is the first thing to send out. See the detailed reminder and collection process from the dropdowns below.
Reminders and payment demands 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.

Assignments

Out of all the invoices transferred to Reskontravahti Express, an assignment is created. Assignment is something through which the company can follow up the process on the Visma Amili side. Assignment is also used for all the communication between the sender company and Visma Amili. 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 Amili will handle the reminder sending and debt collection process depending on the chosen collection type.
2. Partially closed - The assignment has been paid but the customer still has open charges which Visma Amili will continue to collect.
3. Closed - The assignment is closed. The assignment has been paid and no charges are open. Visma Amili has transferred the money to company’s account.

[
  {
    "id": "fa9781ba-20d1-4677-a125-f04bff7bbac0",
    "status": "open",
    "collection_status": "reminder_sent",
    "service_level": "default",
    "debtor": {
      "name": "Test receiver Oy"
    },
    "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": "Amili Oy FI"
          }
        ],
        "created_at": "2020-04-15T21:01:18Z",
        "happened_at": "2020-04-16T00:00:00Z"
      }
    ]
  }
]

REST API for assignment handling.

Events

Parties connected to an assignment (sender company and Visma Amili) can add events to communicate changes to the assignment. Events describe what has happened to the assignment for example when the remainder is paid Visma Amili will add an Paid event to the assignment. Events can also be used to update assignment information from the sender side like informing direct payments. Events can be considered as a communication channel between Visma Amili and sender 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 Amili 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"
    }
  }

Message functionality

Messaging functionality is used for the communication between Visma Amili and the customer. Customer can add a comment or question related to the assignments or Visma Amili 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.

REST API for message handling.

Closing the service

Reskontravahti Express can be closed by calling DELETE /v1/services/receivables or then by closing the service through the user interface. Visma Amili 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 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 4 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 the 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 the PDF image and any other invoice attachments. If the total size of the attachments is larger than 5 megabytes the recipient will be instructed to download using a link provided in the email.
In Finland, virtual barcode is also added into the email body when sending invoice with image attached.

• Send all invoice e-mails with merged PDF attachments:

Selecting this option means that all invoice e-mails will contain the PDF image and any other invoice attachments. All the PDF attachments and invoice image will be merged into one file. This can be helpful when sending to scanning services. If the total size of the attachments is larger than 5 megabytes the recipient will be instructed to download using a link provided in the email.
Note! Sending with merged PDF attachments does not work with signed PDF files.
In Finland, 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.