Amili Kassavirta

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

Receivables management process

Step by step default process flow

Activation of the service. When the service is activated all the invoices are routed through the Receivables Management service (with few exceptions).
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.
Maventa gives the invoice content to Visma Amili for modifications (What information is changed and why).
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.
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.
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.

If you are using your own invoice image and payment details with the service, this does not fully apply. Read more about using your own image and payment details.

Exceptions on invoices routed through the service

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.
Service does not support the following invoice XMLs: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL, Facturae.
Consumer e-invoices to netbanks are not routed immediately through the service after the activation. There will be a 5 days delay during which all the consumer e-invoices will go directly to the banks instead of going through the Receivables management. This delay should give the company enough time to update their consumer agreements (SI-messages) with banks. After the delay the consumer e-invoices are also routed through the Receivables management like all the other invoices. See more from How to handle Finnish consumer invoicing

Invoice content requirements and error handling

Full receiver’s address information is given

If there is something missing from the receiver’s address details your invoice will end up in the error state with the following error message SEND ERROR (REASON: RECEIVABLES-SERVICE: Postal code for CITY_NAME xxxxxx not found (code #5)).

Invoice will not be sent out to the receiver. You will need to create a new invoice with the corrected address details and send it again.

Due date is not in the past and there is at least 3 days until the due date

If due that has passed or it is within 3 days your invoice will end up in the error state with following error message SEND ERROR (REASON: RECEIVABLES-SERVICE: The due date for the invoice is within three (3) days or has already passed (code #13)) Invoice will not be sent out to the receiver. You will need to create a new invoice with a proper due date and send it again.

Sum of lines must equal the total sum of the invoice

Duplicate invoice numbers are not allowed in most cases

Ensure that each invoice number is unique, avoiding any reuse. However, there are few exceptions to this rule:

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.
If a new invoice has the same invoice date as an existing 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.
If a new invoice has the same invoice date as an existing open assignment with no associated 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.

See the detailed chart for duplicate expections

In case the invoice number needs to be unique, you will receive the following error message and sending will fail completely (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 e5006e70-dfab-49da-90fd-2e47d2eb8ea6)).

You will need to create a new invoice with a unique invoice number and send it again. It is highly recommended to prevent the use of the same invoice number already when a user tries to create an invoice in the ERP. This to avoid unnecessary error handling.

Note! If the invoice ends up in any of the above mentioned errors prefixed with SEND ERROR (REASON: RECEIVABLES-SERVICE.., the invoice IS NOT SENT to the receivables service which means that it won’t be sent to the receiver either. Sender needs to make the needed corrections for the invoice content and resend the invoice.

Below is explained how to handle the error cases when the invoice IS ALREADY SENT through the receivables service when the invoice ends up in the error state:

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

In case the invoice ends up in the error state because of the wrong e-invoice address (for example the receiver doesn’t anymore receive invoices to the e-invoice address that the sender has defined as the address) sender needs to reroute the invoice to a new address. Rerouting can be done either from the user interface under the invoice details or then via API from the ERP. Using rerouting functionality does not create a new assignment.
If the reason for failure is in the XML content, the sender needs to send a new invoice with corrected information. In order to do so the sender probably needs to credit the existing erroneous invoice in the ERP. Addition to crediting the invoice in the ERP the sender needs to communicate that to the receivables assignment in question so that Visma Amili also gets notified to close the assignment. This can be done using the credit_note event. We highly advise to automate this process in the ERP side to always create a credit_note event to an assignment when the user creates credit notes in the ERP. Although marking the assignment as credited can also be done through the user interface. Note! When sending the new corrected invoice, remember to use a new invoice number to avoid the duplicate invoice number error above.

When an invoice ends up in the error state, Visma Amili is notified. In case the sender does not act on the error, and the invoice remains in error state even when the invoice is due, Visma Amili closes the assignment and adds a comment about the closing reason to the assignment details.

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.

If you are using your own invoice image and payment details with the service, this does not fully apply. Read more about using your own image and payment details.

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.

Receivables management process

Schedule in Finnish

Receivables management process

This reminder and debt collection schedule does not apply if the customer has VIP or PREMIUM service level set. Read more FIX LINK PENDING about the service levels for customer

Opening the Receivables Management service

To open the Receivables Management service use REST API method PUT /v2/services/amili/receivables to initiate the activation process. GET /v2/services/amili/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:

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
The GET /v2/services/amili/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.

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

Parameter	Description
iban	Account information (IBAN) that Visma Amili will use when they pay the money they get from the customer (receiver of the invoice). There can only be one account.
bic	Bank identification code e.g. DABAFIHH
bank	Name of your bank
contact_person	Contact person name
contact_email	Email for possible problem cases and contacting
contact_phone_number	Phone number for the contact person
authorization_email	Email for sending the request to sign the electronic agreement. If left blank, email is not sent
accountable_party	“vfsfi” (default) or “company”. If set as “vfsfi” Visma Financial’s account details are used. If “company”, company’s own account details are used (note! only allowed for certain vendors)
service_type	“full” receivables management service or Reskontravahti Auto (default). “express” Reskontravahti Express service
customer_service_email	This email will be shown on the factoring clause that Visma Amili will add to the invoices routed through them
customer_service_phone_number	This phone number will be shown on the factoring clause that Visma Amili will add to the invoices routed through them
billing_address	Billing address for possible service costs related to the debt collection processes in the later phase. Price list
postal_address	Company’s postal 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 /v2/services/amili/receivables call. Read more How to handle Finnish consumer invoicing.

Use GET /v2/services/amili/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

Finnish consumer invoicing

If you have the Finnish consumer invoicing enabled on your company’s account, there is an important change you will need to do before this Receivables Management service can be used with e-invoicing to netbanks. There will be a 5 days delay to do the needed changes. During these 5 days all the consumer e-invoices will still go directly to the banks instead of going through the Receivables Management. After the delay the consumer e-invoices are also routed through receivables Management like all the other invoices. This change will enable consumer e-invoices to be sent to your consumers with the Visma Amili’s IBAN information.

What do you need to do

You will need to update your consumer agreements (SI-messages) by adding Visma Amili provided IBAN to them and to change the SellerInvoiceIdentifierType (type of the identifier asked from the consumer in their netbank when adding the seller as their invoicer).

How to do it

You will need to send CHANGE type sender info messages SI-messages to each bank you have the agreement with and do the following changes:

In the SI-message you will need to add Visma Amili’s provided IBAN number as a new seller account (note! we do not recommend overriding the existing seller account information but instead just add that as a new one).

Addition to adding a new seller account number you need to change the SellerInvoiceIdentifierType if you are currently using either type 01 (national reference number) or 02 (international RF creditor reference). SellerInvoiceIdentifierType defines the type of the identifier the consumer is asked to fill in when they add the seller as their invoicer in their netbank, and with which the invoicer can identify the payer in its system.

Some banks have automated routines to check the seller from the invoice based on the reference number, IBAN and beneficiary name (under EpiBeneficiaryPartyDetails) used and make suggestions for consumers to add as their invoicer. In the case of the Receivables service, the IBAN and beneficiary name used on the invoices belongs to Visma Amili and in that case the consumer might end up actually making the consumer agreement with Visma Amili instead of the actual sender company. Reference numbers are also a bit problematic identifiers because the reference number sent from the ERP is not the same as what the receiver gets and what they would fill in in their netbank. Reference numbers are changed by Visma Amili on the transit. If reference number is used to link new consumer agreements in your ERP’s consumer register you need to check the reference number used by Visma Amili from the assignment details using GET /v1/assignments/{assignment_id} method from the “reference_ids” parameter, value for the type “number”. And then connect that reference number to your register. if you still want to keep using the reference number as the identifier and want to do the connection between your reference number and reference number used by Visma Amili you can switch using SellerInvoiceIdentifierType 08 (other numeric identifier), 09 (other alphanumeric identifier) or 99 (other identifier). These types of identifiers banks do not have any checking routines. In the instructions on the sender info (SellerInvoiceIdentifierText) you can still advise the consumer to give the reference number (“Please give the reference number of your latest invoice”).

Easiest solution would be to switch to using something else than reference numbers as identifiers. Good alternative is customer number.

If there is a functionality to create and send the SI-messages directly from your ERP you can most likely do the change easily through that. If you are unsure if there is such functionality in your ERP or you don’t know how to use it contact your ERP support team. After the messages are created they can be sent through our UI or via the API. More information about SI-messages and a link to message_send method to use for sending.

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 /v2/services/amili/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.

default process

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.

Premium process

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

Vip process

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:

Open - The assignment is open and Visma Amili is monitoring the assignment. On the other words the invoice hasn’t yet been paid.
Partially closed - The assignment has been paid but the customer still has open charges which Visma Amili will continue to collect.
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.

^^^plain start Assignment content

Parameter	Description
id	Assignment id
status	Open (unpaid) / closed (paid or cancelled) / partially_closed (Invoice is paid but not the reminder or collection charges)
collection_status	Tells the collection status of the assignment. Set based on event added by the agency. Values can be “unknown” (default value until reminder is sent/collection process starts), “reminder_sent”, “debt_collection”, “legal_collection”, “recovery_proceedings”, “debt_surveillance”, “lack_of_means”, “payment_plan”
service_level	default (normal process) / premium / vip
debtor	“name”: Name of customer (receiver of the invoice) and “bid”: customer’s bid
due_date	due date from the original invoice or new due date if due date change request is accepted (see Request a due date change event)
issued_at	Invoice date from the original invoice
number	Invoice number from the original invoice
sum	Total sum of the invoice
paid	Amount that is paid or credited
currency	Currency from the original invoice
created_at	When assignment was created
updated_at	When assignment was updated last time (e.g. when paid sum was updated)
partially_closed_at	When assignment was partially closed by Visma Amili
closed_at	When assignment was closed by Visma Amili
reference_ids	Contains three ids: “agency_id” = Visma Financial id, “invoice_id” = id of the original invoice (invoice uuid), “number” = New reference number that was changed to the original invoice

Json example of assignment and its event

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

Collection status of the assignment

collection_status	Events that sets the collection status
unknown	default value until reminder is sent or collection activities are started
reminder_sent	reminder_sent / second_reminder_sent
debt_collection	collection_started (first payment demand is sent) / second_demand_sent / tratta
legal_collection	legal_collection_started
recovery_proceedings	application_for_enforcement
debt_surveillance	credit_loss_suggestion (Note! credit_loss event does not change the collection status
lack_of_means	lack_of_means
payment_plan	payment_plan

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

Comment or question

comment - Add a comment or question. With this event you can add a comment or ask a question from Visma Amili related to the assignment in question. Visma Amili will also use this event for sending comments or questions to your company.

It is highly recommended to follow up closely these comment events. Good solutions would be to build some separate view to list only the comment events for a clear separation from all the other events. In this way you will ensure that senders will easily see if an assignment gets a question or a comment from Visma Amili that they might need to respond to somehow.

NOTE! There is a new improved messaging functionality available now to handle the communication better. More information from the messaging functionality

Both company and Visma Amili can send this event.

Handling payments

paid - This event is used for notifying when assignment gets paid by the customer, for informing direct payment and for marking credit note as used.

*Notifying when assignment gets paid by the customer: Visma Amili will use this event to notify when the customer has paid the assignment either fully or partly. If the customer pays the whole sum Visma Amili marks the assignment as closed (close event is added). If the customer pays more than the invoice sum is the extra money is returned to the customer. So there is no way of paying more than one invoice at a time. Visma Amili won’t save the money to upcoming payments. In account statement (for example SEPA) all the payments done by Visma Amili have VISMA AMILI as a payer’s name abbreviation (name could be shorter or longer depending on bank). This information can be used to identify direct payments which will then have something else as payer’s name.
*Inform direct payments: With this event you can inform Visma Amili if the customer has made a direct payment to your company’s account. Amount paid can be either full or partial payment. Use a comment event if you want to give some additional information related to the payment. If assignment is fully paid Visma Amili will close the assignment afterwards (close event is added). It is really important to use this event to inform the direct payments in order for Visma Amili to know to update the sum that is still open or to close the assignment. We highly advice to automate this event from the ERP when direct payments happens.
*Mark credit note as used: When credit note is sent and connected to an assignment (credit_note event is used) credit note is also needed to be marked as used and that can be done using this event for the credit note and giving the paid sum as negative value. In this way Visma Amili will get the information to also mark the credit note as closed (close event is added). (When connecting a credit note to an assignment through our UI the credit note is marked automatically as used.)

Paid event will update the parameter “paid” in the assignment. the assignment “sum” does not get updated.
```
{
    "type": "paid",
    "data": {
      "sum_paid": 200.5,
      "booked_at": "2019-01-04",
      "archive_number": "12345"
    }
  }
```
Both company and Visma Amili can send this event.

Assignment is closed »> close - This event is used by Visma Amili to mark the assignment as closed. Assignment gets closed when it is fully paid by the customer, marked as fully paid by the sender or if the sender wants to cancel the assignment.

Only Visma Amili can send this event. ^^^

^^^plain start Assignment is partially closed

partially_closed - This event is used by Visma Amili to mark the assignment as partially closed. This is used when invoice sum is fully paid but customer did not pay reminder or collection charges. This means that from the mandator’s perspective the assignment is closed, but the customer still needs to pay more money to the Visma Amili. When assignment gets this event it’s status changes to ‘partially_closed’.

When customer eventually pays the remining reminder or collection charges Visma Amili will add the close event and the assignment status changes to ‘Closed’

Only Visma Amili can send this event.

Request a due date change »> due_date_change_request - Request a due date change. If there is a need to update the due date of an assignment, you can request the change. Visma Financial Solution Oy will either accept or reject the request depending on the new due date and how far in the collection process the assignment already is. If the debt collection process has been started, due date change will be rejected. When a due date change request is accepted you will receive a confirmation event (due_date_changed event is added) about the acceptance and due date is updated accordingly for the assignment (parameter due_date gets a new value).

If request is rejected you will get a comment with the reason for the rejection (comment event is added).

Only company can send this event. ^^^

^^^plain start Confirmation for due date change

due_date_changed - This is an event that will be received when due date change request is approved by Visma Amili. This will update the assignment’s due date. Note! This won’t update the original invoice in question.

Only Visma Amili can send this event.

Connect a credit note to an assignment

credit_note - You can connect a credit note to an assignment by giving the credit note number and credit sum with this event. This event is added for the assignment in question you want to connect the credit note to. Give the credit note sum as positive value in the request. If assignment is fully credited Visma Amili will close the assignment (close event is added). If the credit note is sent through Maventa you will also need to mark the credit note as used and connected by adding a paid event to the credit note assignment and give the paid sum as negative value. If the credit note is not sent through Maventa you should still use this event to inform Visma Amili for crediting the assignment so that they know to close the assignment, or if only part of the assignment is credited they will continue payment monitoring and possible debt collection process with a different sum.

If whole assignment is credited with the credit note:

ssignment gets credit_note event with credit sum given as positive value Credit note gets paid event with paid sum as negative value

We highly advice to automate this event in the ERP side to always create credit_note event to an assignment when user creates credit notes in the ERP.

Only company can send this event.

Cancel the whole receivable management for the assignment

cancel - You can cancel the whole receivable process for the assignment. Please note that this will close the assignment (close event is added) and the closing cannot be reversed or modified afterwards. Visma Amili will not monitor the assignment or take actions to collect the debt. Company is then responsible for monitoring the assignment. Do not use this for reporting a credit loss. Note! If reminder or collection actions have already been initiated, Visma Amili will charge the client a cancellation fee.

Only company can send this event.

Temporary suspension of debt collection - Request and update

freeze - You can request to suspend the debt collection process for the assignment in question until the specified date. Please note that once the suspension has been set, Visma Amili will not monitor the assignment or take actions to collect the debt. Company is then responsible for monitoring the assignment. The suspension can be requested until the legal collection has started or the enforcement authority has found the customer insolvant. The debt collection will automatically continue after the expiration date. You can request an update to the debt collection suspension expiration date by choosing a new date or you can end the suspension by setting today as the expiration date.

Set the parameter “frozen” to true

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

Only company can send this event.

Temporary suspension of debt collection - confirmation

freeze_confirmed - This event is added by Visma Amili as a confirmation when the Temporary suspension of debt collection has been set to an assignment.

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

Only Visma Amili can send this event.

Temporary suspension of debt collection - Termination

unfreezed - The Temporary suspension of debt collection has been terminated and the debt collection of the assignment will continue.

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

Only Visma Amili can send this event.

Information for interest payments

interest_paid - With this event Visma Amili will inform if there was interest paid for an assignment and what was the interest amount. This event is usually received at the same time than the paid event. Interest will be paid daily as one payment that contains all the interests from the same day. Message in the account statement is “Korkotilitys PVM”.

Interest in this matter is the one defined by the sender for their invoices if the receiver does not pay on time. Note! Interest needs to be defined on the invoice XML. It is not enough to have it only on the invoice image.

Only Visma Amili can send this event.

Cash discount used

cash_discount - With this event Visma Amili informs if the customer used cash discount on the payment and how much was the cash discount amount.

paid sum + cash_discount sum = assignment’s sum

This event is usually received at the same time than the paid event.

Only Visma Amili can send this event.

Notification when the first reminder is sent to the customer

reminder_sent - This event is added by Visma Amili when a first payment reminder has been sent of an unpaid invoice. This event will set the “collection_status” of an assignment to reminder_sent if it is not already set.

Only Visma Amili can send this event.

Notification when the second reminder is sent to the customer

second_reminder_sent - This event is added by Visma Amili when a second payment reminder has been sent of an unpaid invoice. This event will set the “collection_status” of an assignment to reminder_sent if it is not already set.

Only Visma Amili can send this event.

Notification when the first payment demand is sent to the customer

collection_started - This event is added by Visma Amili when a first payment demand has been sent of an unpaid invoice. This event will set the “collection_status” of an assignment to debt_collection if it is not already set.

Only Visma Amili can send this event.

Notification when the second payment demand is sent to the customer

second_demand_sent - This event is added by Visma Amili when a second payment demand has been sent of an unpaid invoice. This event will set the “collection_status” of an assignment to debt_collection if it is not already set.

Only Visma Amili can send this event.

Tratta is sent

tratta_sent - A tratta has been sent of an unpaid invoice. This event will set the “collection_status” of an assignment to debt_collection if it is not already set.

Only Visma Amili can send this event.

Legal collection is started

legal_collection_started - A summons application has been sent and legal collection of the assignment has started. This event will set the “collection_status” of an assignment to legal_collection.

Only Visma Amili can send this event.

An application for enforcement is sent

application_for_enforcement - An application for enforcement has been sent and the assignment has been transferred to the enforcement authority. This event will set the “collection_status” of an assignment to recovery_proceedings.

Only Visma Amili can send this event.

The enforcement authority has found the debtor insolvent

lack_of_means - The enforcement authority has found the debtor insolvent. This event will set the “collection_status” of an assignment to lack_of_means.

Only Visma Amili can send this event.

A payment plan has been agreed on the invoice

payment_plan - A payment plan has been agreed on the invoice. This event will set the “collection_status” of an assignment to payment_plan.

Only Visma Amili can send this event.

A recommendation to mark the assignment as credit loss

credit_loss_suggestion - A recommendation from Visma Amili to mark the assignment as credit loss. This event will set the “collection_status” of an assignment to debt_surveillance.

Only Visma Amili can send this event.

Mark the assignment as a credit loss

credit_loss - You can mark a credit loss on assignment in question. Reporting a credit loss is only done for the accounting purposes and has no impact on the payment control and monitoring. Visma Amili will continue the collection process. Visma Amili will suggest that the sender marks the assignment as credit loss if they know the customer won’t pay it. Note! After posting, the credit loss cannot be reversed or modified.

Only company can send this event.

Service level of the customer

service_level_changed - This event is created by Visma Amili if the customer of the invoice (receiver) is either on the VIP or PREMIUM service level group. If the service level group is changed, there will be a new event added. This event will set the “service_level” of an assignment to default / vip / premium based on the choosen service level group.

Only Visma Amili can send this event.

Other events

Delivery status of the original sent invoice

delivery_status - This event is mainly created for Visma Amili to follow up if the original invoice sending has been successful or if it has failed. This is the only way they can get the information. If the original invoice ends up in the error state and the sender does not act on it, and if the invoice remains in error state even when the invoice is due, Visma Amili closes the assignment and adds a comment about the closing reason to the assignment details.

As an ERP integrator this event might not bring any additional value in your implementation if you are already following up the statuses of sent invoices through the invoice APIs and communicating the errors to the user. In this case these events can be filtered out.

If you want to show these events for the users, there are few things to consider when implementing them:

There will always be at least one delivery_status “DELIVERED” when the invoice is successfully sent. But in most cases there are multiple delivery_status events with status “DELIVERED” depending on the receiving operator. We create one out of each update on the invoice. It might not be necessary to show them all for the user.
If there is delivery_status “FAILED”, the original invoice related to the assignment is in error state. Sender needs to take actions, for example reroute the failed invoice using another route so that it reaches the receiver. After the original invoice is rerouted and sent successfully, a new delivery_status “DELIVERED” is added for the assignment. This is important to show.
In our own UI implementation we only show the first “DELIVERED” event and filter out all the extra ones in case they are “DELIVERED” and there is no “FAILED” ones in between. But if the invoice ends up in the error state, and delivery_status “FAILED” is added, we show that. And then the delivery_status events after the “FAILED” ones to update the correct status for the assignment.

Only Maventa can send this event.

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.

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.

REST API

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

Receivables EUI view with the main menu

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

Receivables EUI view without the main menu

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:

Receivables EUI view for assignment details

Tips for the integrators

Integration scope for Receivables

	Full API integration (all done inside the ERP)	Lightweight Integration	No API integration
Activation	Through API using `PUT and GET /v2/services/amili/receivables`	Full API integration / No API	Through the UI using our form
Consumer invoicing	ERP creates and sends automatically the SI CHANGE messages when service gets activated. The IBAN needed is in the response of GET /v2/services/amili/receivables. ERP handles the targeting of the new RI messages in case reference number is the connecting information: The reference number VFS used in the invoice can be found from the assignment details “reference_ids” and type “number”	Full API integration / No API	User creates SI CHANGE messages and then sends them through our UI. VFS IBAN is shown in the Receivables Settings page. User needs to then also somehow handle the targeting of new RI messages manually
Assignment listing	/v1/assignments, /v1/assignments/{assignment_id} and /v1/assignments/{assignment_id}/events. Assignments could be listed as their own view or then you could think of having the assignment information (and possibility to add event) shown under the invoice details.	Full API integration / No API	User uses our listing of assignments in our UI
Events	/v1/assignments, /v1/assignments/{assignment_id}, /v1/assignments/{assignment_id}/events and /v1/events. You should think a bit how much your users would like to follow up the receivables and which events do they want to see or being able to add themselves. Is it enough to see if there is something happening, for example a comment is added by VFS or if there has been a reminder sent for a customer that hasn’t paid on time? Should these events create some notification on the ERP side when arriving through the API? Adding of events to an assignment is something that should be fully integrated as part of the ERP processes. For example if direct payment comes in then paid event is automatically created from the ERP to the Receivables API. Also having some separate handling for comment events would be beneficial so that important comments or questions from VFS would not get lost and it would be easy for the user to reply	We highly advice to automate at least the events for direct payments (`paid` event) and connecting credit notes (`credit_note` event). Also the request to change a due date and then the confirmation for that (`due_date_change_request`, `due_date_changed`)	User needs to handle all the events through our UI which migh in some cases mean double work. For example requesting a new due date might also then need them to do a change also on the ERP side. Informing of direct payments and connecting credit notes are then on the hands of the sender. These are something that are really important to remember to do so that VFS does not start collection process even though the customer has already paid the invoice

Testing the service

When testing the Receivables integration in our stage environment, please note that the activation step does not work automatically. To complete the activation flow during testing, you’ll need to contact our support team (support@maventa.com), as it requires a manual configuration on Amili’s side. Once activated, the rest of the functionality can be tested as usual. This manual step is only necessary in the test environment—production handles activation automatically.

Closing the service

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.

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.