Amili Perintä

• Only invoices with currency EUR are accepted.
• Valid XML file. The service does not support the following invoice XML formats: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL.
• Full receiver address information must be provided. If any address details are missing, the invoice will not be successfully forwarded to the Amili Perintä service.
• The sum of the invoice 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. However, there are a few exceptions:
  • 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 cancelled 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.

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

A new and improved messaging feature is now available for better two-way communication. See the messaging functionality section for more details.

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 the 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 – Visma Amili uses this event to mark an assignment as closed. An assignment is closed when any of the following occurs:

• the customer has fully paid the assignment
• you report that it has been fully paid (direct payment)
• you report that it has been fully credited
• you request 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 – Visma Amili uses this event 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 – Use this event 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.

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

Only the company can create this event type.

cancel – Use this event to cancel the entire Amili Perintä 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. You become fully responsible for tracking the assignment.
• Do not use this event to report a credit loss.

Only the 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. You become 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 the 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 – Visma Amili uses this event 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.

cash_discount – Visma Amili uses this event to notify if the customer has applied a cash discount on the payment and to indicate the discount amount.

• The sum of the paid amount and the cash_discount amount equals the total assignment sum.
• This event is typically received together with the paid event.

Only Visma Amili can create this event type.

reminder_sent - Visma Amili adds this event when the first payment reminder for an unpaid invoice has been sent. If the assignment’s collection_status is not already set to reminder_sent, the event will update it accordingly.

Only Visma Amili can create this event type.

second_reminder_sent - Visma Amili adds this event when the second payment reminder for an unpaid invoice has been sent. If the assignment’s collection_status is not already set to reminder_sent, the event will update it accordingly.

Only Visma Amili can create this event type.

collection_started - Visma Amili adds this event when the first payment demand for an unpaid invoice has been sent. If the assignment’s collection_status is not already set to debt_collection, the event will update it accordingly.

Only Visma Amili can create this event type.

second_demand_sent - Visma Amili adds this event when the second payment demand for an unpaid invoice has been sent. If the assignment’s collection_status is not already set to debt_collection, the event will update it accordingly.

Only Visma Amili can create this event type.

tratta_sent - A tratta has been issued for an unpaid invoice. This event will update the assignment’s collection_status to debt_collection if it has not already been set.

Only Visma Amili can create this event type.

legal_collection_started - A summons application has been submitted and the legal collection process for the assignment has begun. This event will update the assignment’s collection_status to legal_collection.

Only Visma Amili can create this event type.

application_for_enforcement - An application for enforcement has been submitted and the assignment has been transferred to the enforcement authority. This event will update the assignment’s collection_status to recovery_proceedings.

Only Visma Amili can create this event type.

lack_of_means - The enforcement authority has declared the debtor insolvent. This event will update the assignment’s collection_status to lack_of_means.

Only Visma Amili can create this event type.

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 create this event type.

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 create this event type.

credit_loss – You can mark the assignment as a credit loss for accounting purposes. Reporting a credit loss does not affect payment control or monitoring, and Visma Amili will continue the collection process as usual.

Visma Amili may recommend marking an assignment as a credit loss if it is known that the customer will not pay.

Once submitted, a credit loss entry cannot be reversed or modified.

Only the company can create this event type.

The following events exist but are not applicable when using the Amili Perintä service. They are useful when /integration-guide/accounts-receivable/amili-kassavirta/ is in use:

delivery_status – Tracks the delivery status of the original sent invoice.

service_level_changed – Visma Amili creates this event if the customer of the invoice (receiver) is in the VIP or PREMIUM service level group. If the service level group is changed, a new event is added. This event sets the service_level of an assignment to default / vip / premium based on the chosen service level group. Service levels work with Amili Perintä, but there is generally no need to use them.

due_date_changed – Visma Amili sends this event when a due date change request has been approved. It updates the assignment’s due date.

due_date_change_request – Use this event to request a due date change for an assignment. Visma Amili will either accept or reject the request depending on the new due date and the current stage of the collection process. If the debt collection process has already started, the request will be rejected. When accepted, a due_date_changed event is added as confirmation and the assignment’s due_date parameter is updated accordingly.