Amili Perintä

• Only invoices with currency EUR are accepted.
• Valid XML file. Service does not support the following invoice XMLs: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL, Facturae.
• Full receiver’s address information is given: If there is something missing from the receiver’s address details your invoice will not be successfully forwarded for the Amili Perintä service.
• 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.

comment – Add a comment or ask a question. This event allows you to send comments or questions to Visma Amili regarding the specific assignment. Visma Amili may also use this event type to send comments or questions back to your company.

We strongly recommend monitoring comment events closely. A good approach is to create a dedicated view that displays only comment events, clearly separating them from other event types. This ensures that senders can easily see when Visma Amili has added a comment or question that may require attention or a response.

Note: A new and improved messaging feature is now available to better support two-way communication. More information can be found from the next chapter.

Both the company and Visma Amili can create this event type.

paid – Used to report payments made by the customer, notify direct payments, and mark credit notes as used.

Usage scenarios:

1. Customer payment through Visma Amili. Visma Amili sends a paid event when the customer pays the assignment, either fully or partially.

• If the assignment is fully paid, Visma Amili will automatically close it (close event added).
• If the customer pays more than the invoice amount, the excess is refunded to the customer. Visma Amili does not retain overpayments for future invoices.
• In account statements (such as SEPA), payments processed by Visma Amili appear with VISMA AMILI as the payer name (length may vary depending on bank). This can help distinguish payments by Visma Amili from direct payments, which will show a different payer name.

1. Reporting direct payments Use this event to inform Visma Amili when the customer pays directly to sender company’s account. Payments may be full or partial.

• If additional details are needed, they can be provided using a comment event.
• If the assignment is fully paid, Visma Amili will close it (close event added).

1. Marking a credit note as used When a credit note has been issued and linked to an assignment (credit_note event), it must be marked as used. This is done using the paid event for the credit note, with the payment amount entered as a negative value.

• This allows Visma Amili to close the credit note (close event added).
• If the credit note is linked through the UI, it is automatically marked as used.

The paid event updates the paid field in the assignment, but does not modify the sum value.

{
    "type": "paid",
    "data": {
      "sum_paid": 200.5,
      "booked_at": "2019-01-04",
      "archive_number": "12345"
    }
  }

Both the company and Visma Amili can create this event type.

close – This event is used by Visma Amili to mark an assignment as closed. An assignment is closed when any of the following occurs:

• the customer has fully paid the assignment
• the sender reports that it has been fully paid (Direct payment)
• the sender reports that it has been fully credited
• the sender requests cancellation of the assignment

Once closed, no further collection activity is carried out for that assignment.

Only Visma Amili can create this event type.

partially_closed – This event is used by Visma Amili to indicate that an assignment is only partially closed. This situation occurs when the original invoice amount has been fully paid by the customer, but reminder fees or collection charges remain unpaid. From the sender’s perspective the assignment is finished, but the customer still owes an additional amount to Visma Amili. When this event is added, the assignment status changes to partially_closed.

Once the customer pays the remaining reminder or collection charges, Visma Amili will add a close event and the assignment status will update to Closed.

Closure cannot be reversed or modified.

Only Visma Amili can create this event type.

credit_note – This event is used to link a credit note to an assignment. Provide the credit note number and the credit sum when sending this event. The credit sum should be entered as a positive value.

• If the credit note fully covers the assignment, Visma Amili will close the assignment (close event added).
• If the credit note was issued through Maventa, you also need to mark it as used by sending a paid event for the credit note assignment, with the amount entered as a negative value.
• If the credit note was issued outside Maventa, this event should still be sent to Visma Amili to update the assignment.
• If only part of the assignment is credited, Visma Amili will continue monitoring payments and follow the debt collection process for the remaining amount.

Summary when the whole assignment is credited:

• Assignment receives a credit_note event with the credit sum as a positive value.
• Credit note receives a paid event with the paid sum as a negative value.

We strongly recommend automating this event in your ERP to ensure that a credit_note event is always sent when credit notes are created.

Only company can create this event type.

cancel – This event is used to cancel the entire Amili Kassavirta process for an assignment.

• Once cancelled, the assignment will be closed (close event added), and the closure cannot be reversed or modified.
• Visma Amili will no longer monitor the assignment or take any collection actions, the company becomes fully responsible for tracking the assignment.
• Important: Do not use this event to report a credit loss.

Only company can create this event type.

Request or update Suspension

freeze – Use this event to request a temporary suspension of the debt collection process for a specific assignment until a specified date.

• Once the suspension is set, Visma Amili will not monitor the assignment or take any collection actions. The company becomes responsible for tracking the assignment during this period.
• Suspension requests can be made only if legal collection has not started and the enforcement authority has not declared the customer insolvent.
• The debt collection process will automatically resume after the suspension end date.
• You can update the suspension by providing a new end date, or end it early by setting the expiration date to today.

Set the parameter “frozen” to true:

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

Only company can create this event type.

Suspension confirmation

freeze_confirmed – Visma Amili sends this event to confirm that a temporary suspension has been applied to an assignment.

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

Only Visma Amili can create this event type.

Termination of suspension

unfreezed – Visma Amili sends this event when the temporary suspension has ended and debt collection for the assignment will resume.

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

Only Visma Amili can create this event type.

interest_paid – This event is used by Visma Amili to notify when interest has been paid for an assignment and to provide the interest amount. It is typically received alongside the paid event.

• Interest payments are made daily, with each payment covering all interest accrued on that day.
• In account statements, the payment will appear with the message: “Korkotilitys PVM”.
• The interest in this context is defined by the sender on their invoices for late payments.

Only Visma Amili can create this event type.

reminder_sent - This event is added by Amili Oy 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.

second_reminder_sent - This event is added by Amili Oy 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.

collection_started - This event is added by Amili Oy 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.

second_demand_sent - This event is added by Amili Oy 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_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_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.

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.

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.

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.

credit_loss_suggestion - A recommendation from Amili Oy 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.

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. Amili Oy will continue the collection process. Amili Oy 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.

Following events exists but are not applicable when using the Amili Perintä service. Useful when Amili Kassavirta is in use:

delivery_status

service_level_changed - This event is created by Amili Oy 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. Service levels are working with the Amili Perintä service, but there is really no need to use them.

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

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