Amili Kassavirta

Amili Kassavirta takes care of payment monitoring, payment allocation, sending reminders, and debt collection on your behalf. The service is available for Finnish companies. You only need to create and send invoices as usual, including handling any invoice-sending 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. 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 Amili Kassavirta, with a few exceptions. See what is not routed through the service.

2. Invoice sending from ERP — Send invoices 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, Visma Amili modifies the invoice XML. 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 fields.

4. Sending modified invoice to receiver — Since the invoice XML is modified, Maventa generates a new PDF invoice image 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. You remain responsible for any sending errors and ensuring the invoice reaches the receiver. At this stage, an 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 your 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 7-day delay, during which all consumer e-invoices are sent directly to the banks instead of through Amili Kassavirta. This delay allows you enough time to update consumer agreements (SI-messages) with the banks. After the delay, consumer e-invoices are routed through Amili Kassavirta like all other invoices. See more in requirements for using Amili Kassavirta with consumer e-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 a due date in the 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 cancelled 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. Preventing duplicate invoice numbers in the ERP is strongly recommended 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. You are responsible for ensuring delivery:

• Wrong e-invoice address: If the receiver no longer accepts invoices at the provided e-invoice address, you 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, create a new corrected invoice. Credit the original erroneous invoice in the ERP and send a credit_note event to notify Visma Amili to close the assignment. Automating this process 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 you 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 – Visma Amili adds a factoring clause to indicate that the invoice has been assigned to them for payment handling. This informs the receiver to pay Visma Amili instead of the original sender. You can specify your own contact email and phone number for the factoring clause during the activation process.

• InvoiceFreeText – Visma Amili adds new InvoiceFreeText elements to provide a link to their 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 sends a reminder. For B2B invoices, Visma Amili sends the first reminder 10 days after the due date. For consumer invoices (B2C), the first reminder is sent 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 customer’s language code in the original invoice (Finvoice InvoiceRecipientLanguageCode) determines the language of reminders and debt collection letters. If no language is specified, Finnish is used as the default.

Activating the Amili Kassavirta service

To activate the Amili Kassavirta 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 authorised to act on behalf of the company to complete and sign an electronic agreement with Visma Amili. Authorisation 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, as required under the Money Laundering Act.

Maventa’s partner, Netvisor KYC, handles the authentication and signing process.

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

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

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.

The Amili Kassavirta service can also be activated through the Maventa 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, you must update your consumer agreements before Amili Kassavirta can handle e-invoices to netbanks. There is a mandatory 7-day transition period after activation. During this period, all consumer e-invoices are sent directly to banks and do not pass through Amili Kassavirta. After the transition, consumer e-invoices are routed through the service like all other invoices.

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. Using a reference number is not recommended.

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

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 to 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. Add the new IBAN as one of the seller accounts and update the SellerInvoiceIdentifierType to a more suitable type as described in the previous section.

Use of own invoice image and payment details

You can choose to use your 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 you use your own payment details, all payments are made directly to your 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 section.

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. 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 you. 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 return to the standard debt collection for a customer, simply remove their business ID from the group. 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 is also logged if the service level is VIP or PREMIUM.

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 the 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 the sender’s responsibility.

No payment monitoring

• Invoices for these customers will not be sent through the Amili Kassavirta service.
• The sender’s own account number will be used for payments.
• The 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 you.

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 the 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 the Maventa support team to validate your integration and be added to the allowed list.

Events

Both the sender company and Visma Amili can add events to communicate changes related to an assignment. Events describe actions that have taken place — for example, when a customer pays an invoice, Visma Amili automatically adds a paid event. Events can 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.

Automating event creation from your ERP is strongly recommended. At minimum, automate the paid and credit_note events 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

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

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

APIs for handling messages.

Reporting tool

The receivables reporting tool gives you better insight into your 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. You can choose the one that suits your needs, whether it’s for quick viewing or deeper data analysis.

APIs for reporting tool

Tips for integrators

Testing the service

When testing Amili Kassavirta in the Maventa test environment, please note that activation is not automated. To complete the activation flow, you must contact the Maventa support team as Visma 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

The Amili Kassavirta service can be closed by calling DELETE /v2/services/amili/receivables or by closing the service through the user interface. After the service is closed, new invoices are no longer routed through Visma Amili. Visma Amili will still handle the open assignments.