Amili Kassavirta

Amili Kassavirta takes care of payment monitoring, payment allocation, sending reminders, and debt collection on behalf of the company. The company only needs to create and send invoices as usual (including handling any invoice sending related errors), the service handles everything after that.

The service is provided by Visma Amili (formerly Visma Financial Solutions Oy) and delivered through Maventa. It is included in the Maventa service with no additional fees for using it. The only potential costs are related to the later stages of the debt collection process or if assignments are cancelled. Service contract and price list.

Amili Kassavirta flow

Step-by-step default process flow

1. Activation of the service Once activated, all invoices are routed through the Amili Kassavirta, with a few exceptions. What is not routed through the service.

2. Invoice sending from ERP Invoices are sent from the ERP to Maventa as usual. Ensure the invoice XML is valid and meets the Amili Kassavirta invoice content requirements.

3. Invoice processing by Amili Kassavirta Maventa passes the invoice XML to Visma Amili. During this process, the invoice XML will be modified. For example, the IBAN, payee information, and other relevant fields are updated to reflect Visma Amili’s payment details. See the [full list of modified field].

4. Sending modified invoice to receiver Since the invoice XML is modified, a new PDF invoice image is generated to match the updated data. The modified invoice, the regenerated PDF, and any original attachments are then sent to the receiver through the standard Maventa process. The sender remains responsible for any sending errors and ensuring the invoice reaches the receiver. At this stage, a Amili Kassavirta assignment is created, which can be used to track the process on Visma Amili’s side.

5. Payment The receiver pays the invoice using Visma Amili’s payment information. Visma Amili then transfers the payment to the sender’s account. When an invoice is fully or partially paid, Visma Amili creates an event for the assignment to indicate the payment status.

6. Reminders and debt collection If the receiver does not pay on time, Visma Amili handles reminder sending according to their process schedule and, if necessary, the debt collection process. All updates can be tracked via the assignment events.

Exceptions for invoices routed through the service

1. Only invoices in EUR are accepted. Invoices in other currencies bypass the service and are sent directly to the receivers, with Visma Amili not responsible for monitoring them.
2. The service does not support the following invoice XML formats: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL.
3. Consumer e-invoices to netbanks are not routed through the service immediately after activation. There is a 5-day delay, during which all consumer e-invoices are sent directly to the banks instead of through Receivables Management. This delay allows the company enough time to update consumer agreements (SI-messages) with the banks. After the delay, consumer e-invoices are routed through Receivables Management like all other invoices. See more in How to Handle Finnish Consumer Invoicing.

Invoice content requirements and error handling

Full receiver address**

Invoices must include the complete address. If any part of the address is missing, the invoice will end up in an error state with an example error:

SEND ERROR (REASON: RECEIVABLES-SERVICE: Postal code for CITY_NAME xxxxxx not found (code #5)).

The invoice with missing address details will not be sent to the receiver. You must correct the address, create a new invoice, and resend it.

Due date**

The invoice due date must be in the future, with at least 3 days until it is due. If the due date has passed or is within 3 days, the invoice will end up in an error state:

SEND ERROR (REASON: RECEIVABLES-SERVICE: The due date for the invoice is within three (3) days or has already passed (code #13)).

The invoice with due date in past will not be sent. Create a new invoice with a valid due date and resend it.

Invoice sum**

The sum of the invoice lines must match the total sum of the invoice.

Duplicate invoice numbers

Each invoice number must generally be unique. Exceptions:

1. If a new invoice has a different invoice date than an existing assignment (open or closed), a new assignment with the same invoice number is created.
2. If a new invoice has the same invoice date as a closed assignment with no associated payments or credit notes (manually closed or canceled by the sender), a new assignment with the same invoice number is created.
3. If a new invoice has the same invoice date as an open assignment with no payments or credit notes, and the invoice connected to that assignment is in an error state, the existing assignment is closed, and a new assignment with the same invoice number is created.

If a duplicate invoice number is not allowed, the invoice will fail with:

SEND ERROR (REASON: RECEIVABLES-SERVICE: An assignment for this invoice number xxxx already exists and is still open. If you want to open a new assignment for this invoice number, you must first cancel the existing one (code #6 ...)).

You must create a new invoice with a unique number and resend it. We strongly recommend preventing duplicate invoice numbers in the ERP to avoid these errors.

Handling errors after sending

Invoices are sent through the Amili Kassavirta service just before the invoice leaves Maventa. Errors can occur even days after that. The sender is responsible for ensuring delivery:

• Wrong e-invoice address: If the receiver no longer accepts invoices at the provided e-invoice address, the sender must reroute the invoice. Rerouting can be done through the user interface under invoice details or via the ERP API. Rerouting does not create a new assignment.

• XML content errors: If the error is in the invoice XML, the sender must create a new corrected invoice. The original erroneous invoice should be credited in the ERP, and a credit_note event should be sent to notify Visma Amili to close the assignment. Automating this in the ERP is strongly recommended. The new invoice must use a new invoice number to avoid duplicate number errors.

What information on the invoice gets changed

• IBAN – Visma Amili replaces the payment information on the invoice with their own IBAN. This ensures the receiver pays Visma Amili, who then transfers the funds to the sender using the account provided in the service activation. The original invoice reference number is used for the payment.

• Reference number – Visma Amili replaces the reference number on the invoice with their own.

• Factoring clause – A factoring clause is added to indicate that the invoice has been assigned to Visma Amili for payment handling. This informs the receiver to pay Visma Amili instead of the original sender and ensures that payment instructions are clear. It also provides legal clarity regarding the assignment of the invoice. For the factoring clause, senders can specify their own contact email and phone number during the activation process.

• InvoiceFreeText – New InvoiceFreeText elements are added to provide a link to Visma Amili’s customer service for the receiver: “VERKKOPALVELU: https://www.laskuhelposti.fi/ KIRJAUTUMISTUNNUS: xxxx.” Existing InvoiceFreeText elements are not overwritten, the new ones are added.

• Modified Finvoice XML elements – The following XML elements are updated: SellerAccountDetails, EpiBfiIdentifier, EpiBeneficiaryPartyDetails, EpiReference, EpiRemittanceInfoIdentifier, VirtualBankBarcode, FactoringAgreementIdentifier, FactoringFreeText, InvoiceFreeText

• Invoice image – Maventa generates a new invoice image from the modified XML to ensure the receiver sees the correct information.

Reminder and debt collection schedule

If the receiver does not pay the invoice on time, Visma Amili will first send a reminder. For B2B invoices, the first reminder is sent 10 days after the due date, and for consumer invoices (B2C), 14 days after the due date. Reminders are always sent by regular post. Letters are not sent on weekends or public holidays, which may add a few extra days to the schedule.

The language of reminders and debt collection letters is determined by the customer’s language code in the original invoice (Finvoice InvoiceRecipientLanguageCode). If no language is specified, Finnish is used as the default.

Activating the Amili Kassavirta service

To activate the Receivables Management service, use the REST API method PUT /v2/services/amili/receivables to start the activation process. You can track the activation status using GET /v2/services/amili/receivables.

Activation requires a company representative authorized to act on behalf of the company to complete and sign an electronic agreement with Visma Amili. Authorization can be based on the individual’s position in the company or a power of attorney, which must be attached if applicable. Personal online banking credentials or Mobile ID are needed to complete the form. This is required under the Money Laundering Act to verify the customer and their activities.

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

There are two ways to handle the KYC step from the ERP:

1. Authorization email – By providing an email address in the authorization_email parameter, a link to the Netvisor KYC service is sent to that address. If this parameter is left empty, no email is sent.

2. Direct link from ERP – The GET /v2/services/amili/receivables method returns a link in the activation_url parameter to the Netvisor KYC service. This link can be displayed directly in the ERP. If using this method, leave the authorization_email parameter blank.

Note: If the KYC process is not completed within a week, a reminder email will be sent to the contact person with the activation link.

Information needed for the activation

Parameters for the PUT /v2/services/amili/receivables call

Once the agreement is signed and verified by Visma Amili, the service will be activated, usually within 1–2 business days. You can use GET /v2/services/amili/receivables to check the activation status, or register a webhook to receive a notification from Maventa when the service is activated or rejected.

Amili Kassavirta service can also be activated through our user interface.

How to change information given in the activation

If you need to update company information, please contact your support team, as this cannot currently be done through the API.

Requirements for using Amili Kassavirta with consumer e-invoicing

If Finnish consumer invoicing is enabled for your company, a key update to consumer agreements must be completed before the Amili Kassavirta service can handle e-invoices to netbanks. To allow time for this update, there is a mandatory 7 days transition period. During this period, all consumer e-invoices will continue to be sent directly to banks and will not pass through the Amili Kassavirta service. After the transition, consumer e-invoices will be routed through the service like all other invoices, allowing them to use Visma Amili’s IBAN information.

Key requirements for B2C messaging

To use Amili Kassavirta with consumer e-invoicing, you must update your consumer sender agreements (SI messages) with the following:

1. Add Visma Amili’s IBAN Include the IBAN provided by Visma Amili as one of the accounts used for consumer e-invoices. All IBANs that may ever appear on your e-invoices must be listed in the SI-message, as banks will reject invoices containing any IBAN not included in the message. It is recommended to add the new IBAN as an additional account rather than replacing existing accounts.

2. Update the SellerInvoiceIdentifierType This defines the identifier consumers must provide when adding the company as a sender in their netbank. Reference number is not recommeneded to be used.

Some banks use automated routines to identify the seller based on the reference number, IBAN, and beneficiary name. When using Amili Kassavirta, the invoices will contain Visma Amili’s IBAN and beneficiary name, which could cause the consumer to inadvertently create an agreement with Visma Amili instead of your company when bank suggested an e-invoicing agreement for the consumer.

Reference numbers are also problematic because the number sent from the ERP differs from the one received by the consumer, as Visma Amili modifies it during processing. If your ERP uses reference numbers to link new consumer agreements, you must retrieve the reference number used by Amili Kassavirta from the assignment details (GET /v1/assignments/{assignment_id}, parameter reference_ids, type number) and connect it in your register.

If you are currently using SellerInvoiceIdentifierType as 01 (national reference number) or 02 (international RF reference) you should change it 08 (other numeric identifier), 09 (other alphanumeric identifier) or 99 (other identifier) in the SI-message, for a type that banks do not validate.

How to make the changes

Create CHANGE-type SI messages for each bank you have an agreement with and add the new IBAN as one of the seller accounts and update the SellerInvoiceIdentifierType to something more convenient described in the previous chapter.

Use of own invoice image and payment details

Senders can choose to use their own invoice image and payment details when sending invoices through the Amili Kassavirta service. When this option is enabled, Visma Amili will not modify the payment information, and Maventa will not replace the original invoice image as it normally does in the standard process.

If the company uses its own payment details, all payments will be made directly to the company’s account. In this setup, the ERP must support the full Amili Kassavirta integration, including an automated process for reporting direct payments to Visma Amili via API. This is required so that Visma Amili can correctly update the assignments (mark as paid/closed). See more about Handling payments under the Events chapter for more information.

Restrictions and requirements

Because all payments (except those paid by VISMA AMILI / VISMA FINANC) must be reported as direct payments through the API, this option is only available for selected ERP vendor keys that have been verified to have a reliable, automated direct-payment reporting solution.

If you wish to enable this feature for your integration, please contact Maventa support to request verification and approval.

Configuring who receives the payments

During service activation, the parameter accountable_party defines who receives the payments:

If accountable_party is not set, the default value vfsfi is applied. The parameter can also be updated later via: PATCH /v2/services/amili/receivables → set accountable_party = “company”.

Service levels for customers

If you want to limit debt collection for a specific customer, you can add them to a VIP or PREMIUM customer group. Please note that the default service level is the most efficient option for cash flow and requires no action. Adding a customer to a VIP or PREMIUM group transfers the responsibility for monitoring assignments, preventing expirations, etc., to the sender. In some cases, this may incur additional costs.

Grouping works based on the customer’s business ID, so ensure it is correct both in your records and in the invoice XML when sending. If you later decide to get back to the standard debt collection for a customer, simply remove their business ID from the group. Note that updating a customer group does not affect assignments that have already been closed.

Service levels can be managed via the API using PATCH /v1/service_levels/{customer_bid}

On an assignment the parameter service_level reflects the group: “VIP” or “PREMIUM” if the customer is in one of those groups and “default” if not in a VIP or PREMIUM group.

A service_level_changed event will also be logged if the service level is VIP or PREMIUM. Note: service level updates may take a few hours to appear after an invoice is sent and the assignment is created.

DEFAULT customers

This is the standard payment monitoring process. It is the most efficient for cash flow and requires no action.

PREMIUM customers

• A payment reminder and demand for payment are sent for overdue invoices.
• Collection ends 30 days after the due date of the demand for payment. After this, monitoring and managing the receivable is sender’s responsibility.
• If the invoice is unpaid, a fee of 30€ + VAT applies for the sender

VIP customers

• Only a payment reminder is sent for overdue invoices. No reminder fee is charged to the customer but the sender is billed for a 5€ + VAT fee for each reminder.
• Collection ends 30 days after the due date of the payment reminder, and the case is closed. After this, monitoring and managing the receivable is sender’s responsibility.

No payment monitoring

• Invoices for these customers will not be sent through the Amili Kassavirta service.
• Sender’s own account number will be used for payments.
• Sender is responsible for monitoring, controlling, and managing these receivables.
• No additional costs are charged for this option.

Assignments

Every invoice sent through the Amili Kassavirta service automatically generates an assignment. An assignment represents the invoice’s lifecycle within Visma Amili and is used to track its status, payment progress, and all communication between Visma Amili and the sender.

Each assignment contains the fields reference_ids and invoice_id, which link the assignment to the original invoice using the invoice UUID.

Assignments can have one of three statuses:

• Open – The invoice is still unpaid and Visma Amili continues monitoring and processing it.
• Partially closed – The invoice has been paid, but additional fees or charges remain for Visma Amili to collect.
• Closed – The invoice and all related charges are fully paid, and Visma Amili has transferred the funds to the company or assignment has been credited or closed otherwise.

REST API for assignment handling.

Assignment content

[
  {
    "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"
      }
    ]
  }
]

Collection status of the assignment

Creating assignments manually (without sending the invoice to the recipient)

Assignments can also be created for the Amili Kassavirta service without delivering an invoice to the customer. This is useful in cases where the invoice itself has already been communicated to the recipient outside Maventa.

A common use case is housing companies: they often send one annual invoice covering the entire year, but still need to track and monitor monthly payments. By creating assignments manually each month, payment reminders and collection processes can be triggered automatically if payments are late.

Manual creation of assignments is done via POST ​/v1​/invoices using the parameter prevent_routing = true. When this parameter is enabled, the invoice is marked as SENT immediately, without any delivery to the receiver, and an assignment is created in Amili Kassavirta for normal monitoring.

To use this method, you must provide a valid invoice XML including full recipient address details and a due date in the future. This functionality is restricted to approved ERPs (vendor keys). If you want to enable it, please contact Maventa support team to validate your integration and be added to the allowed list.

Events

Parties involved in an assignment (the sender company and Visma Amili) are able to add events to communicate changes related to the assignment. Events describe actions that have taken place for example, when a customer pays an invoice, Visma Amili will automatically add a paid event. Events may also be used to update assignment details from the sender side, such as requesting a new due date or notifying about direct payments. In practice, events serve as a communication channel between Visma Amili and the sender company.

We strongly recommend automating event creation from your ERP whenever possible. At minimum, the paid and credit_note events should be automated to ensure they are always delivered to Visma Amili, without relying on end users to manually trigger them via the UI.

REST API for event handling.

Event types and usage

Events both parties can use

Events only Visma Amili can use

Events only sender company can use

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

OLET TÄSSÄ

Other events

Messaging functionality

Messaging enables two-way communication between Visma Amili and the customer. Customers can add comments or questions related to their assignments, and Visma Amili can send important information concerning the assignments.

It is strongly recommended to include this functionality in the integration to ensure a reliable communication channel and prevent important messages from being missed.

APIs for handling message.

Reporting tool

Receivables reporting tool has been designed to give customers a better insight into their receivables and collections activity. Reports can be downloaded for a selected date range (up to 365 days). Two report types are currently available:

• Settlement Report: Provides a summary of all settlements made during the chosen period.
• Credit Loss Recommendation Report: Highlights potential credit losses based on historical data.

Both reports are available in PDF and Excel formats, customers can choose the one that suits their needs, whether it’s for quick viewing or deeper data analysis.

APIs for reporting tool

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

Testing the service

When testing the Amili Kassavirta in our test environment, please note that activation is not automated. To complete the activation flow, you must contact our support team as Amili needs to perform a manual configuration. After activation, all other functionality can be tested normally. This manual step applies only to the test environment—activation in production happens automatically.

Closing the service

Amili Kassavirta service can be closed by calling DELETE /v2/services/amili/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.