Ropo Perintä
Ropo Perintä helps
Pääoma, kulut ja korot pitää aina ilmoittaa jokainen erikseen! Ei saa olla yhdessä yhtä pääomana
Kuluttajien vuokrasaatavassa on pakollista antaa vuokran tiedot sekä kuluttajan HETU. Jos HETU puuttuu, toimeksiantoa ei pysty siirtämään Ropolle
Päävelallisen ja rinnakkaisvelallisen tiedot tulee antaa API:ssa erillisinä (HETU + muut tiedot velallisesta)
Toimeksiantoja pystyy siirtämään Ropolle vasta kun laskun eräpäivästä on kulunut vähintään 7 päivää B2B laskujen osalta ja 14 päivää kuluttajalaskujen osalta
To open the Ropo Perintä service use REST API method PUT /v2/services/ropo/receivables to initiate the activation process. GET /v2/services/ropo/receivables method is used to follow up when the service get activated. Also webhooks can be registered to follow up the activation status
To complete the activation process, a person authorized to act on behalf of the company must fill and sign an electronic agreement with Ropo. 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/ropo/receivablesmethod 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/ropo/receivables call
| Parameter | Description |
|---|---|
| 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 |
When agreement is signed and verified by Ropo the service gets activated. This happens usually within 1-2 workdays.
Use GET /v2/services/ropo/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).
B2B invoices with due date 14 days can be transferred to the Ropo Perintä service via the following API methods:
Transfer invoice:
POST /v1/invoices/{id}/assignment
As an input you will need to provide the invoice id (uuid) for an over due invoice, and the preferred collection type
reminder_and_collection - transfer the invoice to a full reminder and debt collection process collection - transfer invoice directly to the collection process as you have already handled the reminder sending yourself
Possible errors:
If the due date of the invoice is not in the past, the API returns the following error as only invoices having due date in past can be transferred:
Error: response status is 400
{
"code": "invalid_parameters",
"message": "Request parameters are invalid",
"details": [
"Invoice not expired"
]
}See the status of the transfer:
GET /v1/invoices/{id}/assignment
Pending - Waiting for the transfer Sent - Transfer successful and an assignment is created. Response will also contain a link to the newly created assignment Error - Trasfer failed (Most common reason is missing receiver’s address details)
Invoice content requirements
- 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 to the Ropo service
- 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.
There is a possibility to transfer invoices, that have not been sent through Maventa, for the Ropo Perintä service. This means adding an assignment manually to the service.
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. After the invoice is created, above mentioned Ropo Perintä APIs can be used to transfer the invoice to the reminder and/or debt collection process.
Creating assignments manually will have a debit action and it will be billed according to the existing price lists.
When invoice is transferred to Ropo service for reminder and collection process Ropo will send out the first reminder 10 days after the due date of the invoice for B2B invoices, and 14 days after due date for consumer invoices (B2C). In case invoice is transferred directly to the collection process, payment demand is the first thing to send out. See the detailed reminder and collection process from the dropdowns below.
Reminders and payment demands 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.
Out of all the invoices transferred to Ropo Perintä, an assignment is created. Assignment is something through which the company can follow up the process on the Ropo side. Assignment is also used for all the communication between the sender company and the collection agency. 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 Ropo will handle the reminder sending and debt collection process depending on the chosen collection type.
- Partially closed - The assignment has been paid but the customer still has open charges which Ropo will continue to collect.
- Closed - The assignment is closed. The assignment has been paid and no charges are open. Ropo has transferred the money to company’s account.
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, Note! Does not apply to Ropo |
| debtor | “name”: Name of customer (receiver of the invoice) and “bid”: customer’s bid |
| due_date | due date from the original invoice |
| issued_at | Invoice date from the original invoice |
| number | Invoice number from the original invoice |
| sum | Total sum of the invoice (taken from the invoice data if not given in the API when transferring the assignment ) |
| 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 |
| closed_at | When assignment was closed by Ropo |
| reference_ids | Contains three ids: “agency_id” = Ropo id, “invoice_id” = id of the original invoice (invoice uuid), “number” = Reference number from the original invoice |
Json example of assignment and its event
[
{
"id": "fa9781ba-20d1-4677-a125-f04bff7bbac0",
"status": "open",
"collection_status": "reminder_sent",
"service_level": "default",
"debtor": {
"name": "Test receiver Oy"
},
"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": "FIX LINK"
}
],
"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 |
Events are added to the assignments ones something happens in Ropo side like a payment is done by the customer. Also sender can add events to communicate things to Ropo like direct payments to the sender’s own account or if they want to credit the invoice
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 Ropo without needing to rely end user to remember to do these themselves.
REST API for event handling.
Ropo Perintä can be closed by calling DELETE /v2/services/ropo/receivables. Ropo 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.