Home Integration guide Companies and settings

Company account management & Customer Authentication

You can use either the SOAP API, REST API or the web user interface to open and manage company accounts. However, the user interface requires manual work so if the integration will have multiple companies or a complex set-up, API is recommended.

How to open and activate company accounts

Create company account
Configure settings for the account
Verify the account (customer authentication) either with
1. Visma Sign - customer signs electronically to verify account (default)
2. Partner’s own customer authentication process

1. Create company account

Call the API to register a new company with basic settings.

SOAP

register_with_password The method registers a new company account with default settings and adds/creates a user based on the email in the user_email parameter

Note how the user creation works!

If user given in the user_email parameter doesn’t exist, a new user is created based on email and added to the company
If user given in the user_email parameter exists, this existing user is added to company

In situations where a new user is created, method returns unique company_uuid and user_api_key. If method is called with an existing user, for security reasons only company_uuid is returned.

REST

Creating a company requires a vendor key and a user API key. You may use an existing user or create a new one.

Existing company

There can be only one company per business id. If the business id already exists in Maventa you will get an error message when trying to register it again (BID ALREADY TAKEN). Please contact Maventa support (support@maventa.com) regarding the management changes of the already existing account.

In REST API you can check beforehand company’s availability with

POST /v1/partner/lookups/companies

When registering a new company account, it gets automatically linked to your vendor. If you take an already existing company account into use, remember to link the company account to your vendor. This is necessary for correct reporting and support handling and also mandatory if you wish to use webhooks. Similarly if a company stops using your vendor, it should be unlinked.

SOAP

link_vendor_api_key Link vendor API key
unlink_vendor_api_key Unlink vendor API key

REST

POST/v1/company/vendors Link vendor API key
DELETE/v1/company/vendors Unlink vendor API key

2. Configure account settings

When company account has been created, it can be configured by updating company settings and adding new users.

Note To be able to send, receive and activate services you need to first verify the account by Know You Customer process.

Keep Active

Keep Active is a feature for companies that rarely generate transactions. To maintain your company account as active even without generating transactions within a year, use the “Keep Active” feature.

As part of our data maintenance efforts, we will disable inactive company accounts, which means accounts with no transactions in the past 13 months. An email alert will be sent to the account after 12 months of inactivity, notifying that the account will be automatically disabled in one month. This provides time for companies to take appropriate action. If there is no activity after 13 months, the account will be disabled.

In REST API you can trigger Keep Active function with

POST/v1/company/keep_active

SOAP

API methods:

configure_company Method to change company’s settings.
show_company_configuration Method to view current settings of a company.
user_create_e Method to create new users or adding existing one to a company account.
scan_account_order Method to activate Scan account for the company.

You can update the receiving setting (enable/disable) also using company_invoice_receiving. Note, that invoice receiving needs to be enabled in order to register company account to Peppol network or to use additional services.

REST

API methods:

PATCH /v1/company/settings change company’s settings.
GET /v1/company/settings view current settings of a company.
POST /v1/users add new or existing user to a company.
POST /v1/company/notifications register webhooks

3. Verify account / Customer authentication process

Verifying the account is a step that is done to know that a person with right to represent the company has confirmed and approved registration to Maventa service, before account is activated..

Customer authentication process is important to prevent potential misuse of service. Before verification is completed account cannot be used for sending or receiving. To use the account it is also required that the customer has accepted the Terms of Service .

Note that for Finnish companies, verification creates also automatically the request to open bank network.

Customer authentication options

The customer authentication process can happen on the integrators side or with Visma Sign electronic signature service when customer’s account is opened in to Maventa.

If you want to use own customer authentication process, you need to check with Maventa that your process to authenticate the customer meets the verification requirements.

Visma Sign is always used if customer’s account is registered over Maventa UI.

Visma Sign authentication

The account verification takes place with Visma Sign electronic signature service. A person who has rights to represent company (signing rights or power of attorney) authenticates strongly with bank credentials, BankID or mobileID and signs a document where they confirm that account can be taken into use for the company.

Strong authentication via Visma Sign is currently available for the following countries: Finland, Sweden, Norway, Denmark and Netherlands.

Integrators own customer authentication process

When customer has been already strongly authenticated on the integrator side the account can be taken in use without any additional signing from customer.

The integration must provide an identifier per each company to link to verification event on their side (e.g. contract number, signing eventID). If needed integrator has to be able to show that the customer authentication has happened.

What is meant by strong authentication

Strong authentication includes an element that enables the service provider to verify the identity of the user with certainty. It can be implemented e.g. with login codes of online banks, mobileID, bankID, an electronic identity card or passport.

APIs to use

Verification happens by calling API method after account has been created.
When the verification happens account status changes from unverified (-1) to verified (1) and the account is ready to be used.
In order to start sending and receiving invoices the company_state needs to be verified (1).

REST

POST /v1/companies/authorizations Authorize a company
GET /v1/companies/{id}/status View company authorization status

SOAP

authorize_companies Authorize a company
company_auth_status View company authorization status

Verification statuses

Company_state	Description
verified (1)	Company is verified and customer authentication has been completed. Account can be used to send, download and activate additional services.
unverified (-1)	Authentication required. Sending, downloading and activating additional services is not possible.
unknown (0)	Authentication functionality not in use. Account has not been verified with authorize_companies method, but can be used to send, download and activate additional services. This status is possible for older accounts / integrations.

NOTE! Sending or receiving of invoices is not allowed if company_state is unverified (-1) and API will return error message “Unauthorized”. Invoices can be sent and received after the authorization is done.

Verification webhooks

You can use webhooks to get notifications when company status changes.

You can also register webhook to monitor bank network opening for Finnish companies. The request to open bank network is sent after the verification is completed. The opening is approved by third party (bank) and it usually takes couple of days.

Visma Sign authentication process in production

The signee/authoriser needs to be person who has rights to represent company (signing rights or power of attorney).
You can use parameter locale to select the language for the PDF document.
The invitation to sign is valid for 7 days. If signing is not done in this time, new request needs to be sent.
Company’s authorisation status is automatically updated from Visma Sign every 15 minutes.

Visma Sign authentication process in testing and Visma sign testing credentials

In testing, the flow is similar as above but there are no automatic updates. You need to call API to get the company’s status updated.

SOAP company_auth_status
REST GET /v1/companies/{id}/status

You can complete Visma Sign authorization request with these test credentials:

user ID: testtest@test.test
password: xO70MVYD0CXaKcQ2

For bankID you can use Nets test users from https://www.nets.eu/developer/e-ident/eids/Pages/testusers.aspx

Verify multiple accounts with one signing

In cases where the same signee has rights to represent multiple companies it is possible to use one signing to verify the accounts at the same time. For example in case of a housing company or accounting office that power of attorney for multiple customers. One API call can be used to authorize up to 50 companies in time. For the authorisation to work, the companies that are authorised need to be from the same country.

When this option is used the sign PDF contains a list of all companies to be verified.

Example - Visma Sign verification

You have created company account, at this point authorisation status is (-1) = unverified. To initiate Visma Sign process to call authorize_companies / POST /v1/companies/authorizations API method.

After Visma Sign flow has been completed, account is set to verified state (1) and is ready to be used.

Example SOAP API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sec="https://secure.maventa.com/">
  <soapenv:Header/>
  <soapenv:Body>
    <sec:authorize_companies soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <api_keys xsi:type="sec:ApiKeys">
        <user_api_key xsi:type="xsd:string">accesstoallcompaniestobeverified</user_api_key>
        <vendor_api_key xsi:type="xsd:string">vendorkey</vendor_api_key>
        <company_uuid xsi:type="xsd:string">acompanyuserhasaccessto</company_uuid>
      </api_keys>
      <auth_email xsi:type="xsd:string">emailofsigner@signer.com</auth_email>
      <company_ids xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[1]">
        <xsd:string>513202b6-a681-4061-bfc0-23e4983fc070</xsd:string>
      </company_ids>
      <locale xsi:type="xsd:string">FI/SE/NO/EN/DK</locale>
      <options xsi:type="xsd:string"></options>
    </sec:authorize_companies>
  </soapenv:Body>
</soapenv:Envelope>

Visma Sign flow

1) Request to sign sent to an email given in the API call

2) Signee logs into Visma Sign with a password given in the email

3) Signee sees a document that contains statement of authorisation and accepting attached Terms of Service

Text in the document
- Authorisation for company “CompanyName (BID)” I assure that I have the right to represent (signing rights or power of attorney) the company “CompanyName (BID)” and hereby authorise it for sending and receiving of electronic documents. By signing this document I accept the Terms of Service (below). The signing of this document does not cause any expenses for the company. Visma Solutions Oy only invoices the company “CompanyName” based on the number of sent and received documents and activated services according to the valid price list.
- For Finnish companies the document also mentions of the bank network opening

4) Signee authenticates strongly and signs the document electronically in Visma Sign.

After signee has selected their preferred authentication method and performed the authentication they can see a button “Sign document”.

5) Signing is ready

Example - Integrators own customer authentication process

You have created company account, at this point authorisation status is (-1) = unverified. To verify account call authorize_companies / POST /v1/companies/authorizations API method.

In the API call you must provide an identifier per each company to link to verification event (e.g. contract number, signing eventID).

After the API call, account is set to verified state (1) and is ready to be used.

Example SOAP API request

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:sec="https://secure.maventa.com/">
  <soapenv:Header/>
  <soapenv:Body>
    <sec:authorize_companies soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <api_keys xsi:type="sec:ApiKeys">
        <user_api_key xsi:type="xsd:string">accesstoallcompaniestobeverified</user_api_key>
        <vendor_api_key xsi:type="xsd:string">vendorkey</vendor_api_key>
        <company_uuid xsi:type="xsd:string">acompanyuserhasaccessto</company_uuid>
      </api_keys>
      <auth_email xsi:type="xsd:string"></auth_email>
      <company_ids xsi:type="sec:StringArray" soapenc:arrayType="xsd:string[1]">
        <xsd:string>company_uuid_to_be_verified</xsd:string>
      </company_ids>
      <locale xsi:type="xsd:string">FI/SE/NO/EN/DK</locale>
      <options xsi:type="xsd:string">{"authorization_method":how+identifierlinkingtoauthevent"}</options>
    </sec:authorize_companies>
  </soapenv:Body>
</soapenv:Envelope>

Company accounts over UI

New companies with a new user can be created for:

Testing at https://testing.maventa.com/registrations
Production at https://secure.maventa.com/registrations

If you need to create a new company for an existing user, log-in to Maventa UI first.

Before production account can be used it needs to be verified using strong authentication and electronic signing. When the user logs in to the account for the first time, user needs to go through a set-up wizard where they add information of the company and configure some of the basic settings. The last step of the wizard is the company verification process with Visma Sign service. This process is the same as described within the Visma Sign verification process above, but in this case the signing is initiated from the UI.

Note

The language of the PDF document is defined based on company country.
The language of the Visma Sign invitation email is defined based on the language that is set for the user interface at the time the verification request is sent. E.g. when UI is in Finnish, Visma Sign email is sent in Finnish.

Partner accounts

In Maventa there are two type of accounts; Company accounts and Partner accounts. Company account is the default account type. Partner accounts are used by the integrating partners (ERPs and such with multiple customers).

The key difference between a Partner and a regular Company account is that Partner accounts have an own identifier, vendor_api_key, that is used to link actions to the partner company. The vendor api key is used for billing and reporting purposes. One Partner company can own many vendor_api_keys, for example one for each country they have customers in.

Integrators don’t need to worry about controlling the account types, all accounts registered to Maventa are first created as Company account and changed to account type Partner if and when needed by Maventa.

FAQ

Q: I am testing Visma Sign in test environment, the signing has been done but the status is not updating. What is wrong?

A: There is a difference in status updating between stage and production. See Visma Sign testing here