Detect Service Guide

What is Detect service

Detect is an automated checking service for suppliers and purchase invoices. Detect checks and notifications aim to support companies in supplier management, automating invoice handling, spotting potential fraud attempts as well as in general preventing mistakes in payments and bookings. The service is integrated as part of invoice receiving, so the notifications can be shown to the company always in the right context.

Currently the following checks are available in the service

• VAT check - If value added tax on the invoice, see that the supplier is found in the VAT register
• Supplier activation check - For scanned invoices, check if supplier could have sent the invoice electronically
• BID check - Check the sender business identifier against central business and bankruptcy registers. Available for invoices from Norwegian and Finnish senders.
• Warning list check Check the invoice sender against registers containing warnings against suspected fraudsters and business scams/swindles.

How does Detect service work

Detect is integrated as part of incoming invoice handling over the REST API.

• Detect checks are first activated by the receiver company. After this all company’s incoming invoices coming to Maventa are automatically checked. When the invoice becomes available for download, also the check results are available to fetch and to display to company.

• Maventa runs the checks and provides ready made descriptions, notification statuses and messages for them. Texts and translations are available in EN, NO, FI, SE, DK and NL.

• Activation and showing the check results takes place on integrated system (company’s financial software/ERP).

Integration requirements

Process

1. Activate Detect PATCH/v1/services/detect/checks
2. Fetch results GET /v1/invoices/{id}/detect_results
3. Present results

Contractual requirements

• Customer has accepted the Terms of Service for Maventa
• Customer has accepted the General Disclaimer for the service (available at the end of this guide)

Building the integration

Detect uses the AutoXchange API (REST)

• Production
• Stage

Authentication

General instructions for REST API authentication are explained here

For Detect, use "Authenticate as a company" - option and select the authentication scope "analysis".

Example flow - activation & usage

1. Service activation

To take the service into use for company, user activates the checks they want to start using. Note that before activating the service the user needs to be shown and accept the General service disclaimer.

DO:

1. Show user the General service disclaimer.

2. Show available checks and their descriptions
   • Use GET/v1/definitions/detect/checks endpoint to see the available checks and information related to them
     • all the information e.g. what registers are used for which checks are available over this endpoint.
3. Activate the checks for a company
   • Use PATCH/v1/services/detect/checks to activate checks
   • Give the checks you want to activate (array of strings) for the specific company
   • After you receive status `OK, the checks have been successfully activated. From now on these checks will be automatically triggered for the company’s incoming invoices

• Use GET/v1/services/detect/checks to return the detect settings and see which checks are activated.

Example check activation in user interface

2. Checks are run on incoming invoices

After activation all company’s incoming invoices are automatically checked. When running the checks is ready, the invoice is released to customer’s inbox and check results are made available over the REST API.

Invoice and the attachments are downloaded as usual (see invoice receiving). Detect check results are downloaded with an own API call.

DO:

Fetch the check results from Maventa

• Use GET /v1/invoices/{id}/detect_results to download the check results based on invoice id

About result handling

• Response includes results for all the checks company has activated - only one call is needed to get all the results
• When the invoice is ready to be fetched, Detect check results are also ready.The flow is built in a way that invoices are not released to be listed or downloaded before the checks are run. This means that when you are able to list the new incoming invoices also the check results are ready for fetching.
  • If there are issues with running the checks (e.g. external register down) checks are tried to be run again
  • invoice waiting time max 4 hours - if the check could not have been executed during that time frame the check will go to failed status

3. Notifications are displayed to user

After check results are fetched, relevant notifications are shown to user.

If something is spotted on the invoice, this is shown to user by notification message as part of handling the incoming invoices.

DO:

• Display message to user in relevant place in your system. This can be e.g. as part of views of invoice listing, invoice booking or invoice approval.
• See all possible results over GET/v1/definitions/detect/checks endpoint

Example result visualisation in user interface

4. Check/service closing

Same method that is used to activate the checks is used to deactivate them:

• Call PATCH/v1/services/detect/checks to change what checks are used

Closing the service happens by deactivating all the checks.

General Disclaimer

Visma does not warrant that the customers use of the check services will be uninterrupted or error-free, or that the service and/or the information obtained by the customer through the Services will meet the customers requirements. The customer acknowledges and agrees that the check services will evolve over time and that functionality may be added and removed from time to time. The customer assumes sole responsibility for results obtained from the use of the check services and for conclusions drawn from them. Visma shall have no liability for any damage caused by errors or omissions in any information, instructions, warnings or flags provided to the customer in connection with the check services, or the customer’s actions or non-actions in response to such information.

Useful links

• Warning list guide
  • Details of the warning list check and the used warning registers
  • This guide can be linked to customers directly or it can be used as a basis for writing user support documentation.
• Warning list criteria
• Fraud reporting
  • As part of the warning list check Detect uses fraud reports from customers. See more details of fraud reporting and how to integrate to it.