The solution is designed to be flexible and thus can be used for several different use cases. For this reason, the input data used to request an onboarding URL may be either generic and used by many payers, or specific to a single payer. We will demonstrate this by documenting example use cases below. But first, an overview of all available input fields:

By providing the relevant data above, a payee can generate URLs which may be shared with payers for onboarding.

When a payer is directed to an onboarding URL, the values provided when the URL was originally generated will be set by default. However, the values of these fields may be supplemented and/or overridden by including POST data in the request to the short URL itself.

For example, assume the onboarding URL https://pvu.nets.no/c/1234abcd was generated with the following data:

{
"notificationDisabled": true,
"returnUrl": "https://www.payeepage.com/thank-you",
"purpose": "General Donation",
"storeDebtor": true,
"supplementDebtorData": true,
"campaignId": "123",
}

When the payer is directed to the URL, it may be done as a POST request with the following POST data:

{
“kid”: “123456789”,
"notificationDisabled": false,
"recruiterId": "321",
}

Note that data which was originally associated with the URL is supplemented and overridden by these three values for this session only; future sessions will default back to the values originally used to create the short URL, unless they are overridden again. In other words, the data provided in a POST request to an onboarding URL are session-specific.

Use Cases

Use case 1: Distributing links to new and existing customers

Whether a payer is a new or existing customer, a payee may request an onboarding link which can be shared with the payer to initiate recurring payments via AvtaleGiro. Such a link may be used on the payee’s website where the payee is logged in, it may be sent via email to be used at the customer’s convenience, or it could be sent via SMS at the point-of-sale for immediate onboarding in a face-to-face or phone-based interaction.

An example onboarding URL can be requested by the payee, pre-configured with the following data:

{
  “companyAccountNo”: 12345678901,
  “companyName”: “Bedriften AS”,
  “kid”: “123456789”,
  "returnUrl": "https://www.payeewebsite.com/new-customer/welcome",
  “agreementType”: “ATG”,
}

Note: The KID should be generated by the payee’s ERP or CRM system in accordance with the KID configuration in the payee’s AvtaleGiro agreement.

The URL returned, for example https://pvu.nets.no/c/1234abcd, may be shared via any appropriate channel, and the customer can follow the link for a simple mobile-friendly onboarding process which can be completed in 30 seconds.

Use case 2: Face-to-face NGO donor recruiting

A recruiter for an NGO may approach passers-by on the street to discuss the work the organisation is doing and request that the person support the cause by becoming a regular monthly donor. Using a simple application on a tablet device, a new donor can enter a monthly donation amount and submit it. This form submission would initiate a request to a pre-configured onboarding URL.

For example, assume the onboarding URL https://pvu.nets.no/c/1234abcd was pre-configured with the following data:

{
  "returnUrl": "https://www.ngo.com/thank-you",
  "purpose": "Climate crisis",
  "storeDebtor": true,
  "supplementDebtorData": true,
  "campaignId": "123",
  "companyAccountNo": 12345678901,
  "agreementType": "ATG"
}

When the payer is directed to the URL, it may be done as a POST request with the following POST data:

{
  "kid": "123456789",
  "recruiterId": "321",
  "amount": "1000",
}

The new donor will then authenticate/identify with BankID or BankID for Mobile, confirm or edit personal information and information related to AvtaleGiro, and submit. On submission,

• The donor is directed to the pre-configured return URL - https://www.ngo.com/thank-you,
• An AvtaleGiro mandate is submitted to the donor's bank for processing/confirmation,
• Information related to the donor is stored for the NGO to pick up later via an API call. This can then be stored in the NGO's ERP/CRM system(s).
  

Use case 3: Online and print advertising

A payee may wish to advertise online in channels such as social media and search engine marketing. Using the Link Generator, the payee may request a link which is generic enough that it may be used by multiple users. When this link is clicked, a new customer can be identified, share their personal information with the payee, and set up recurring payments all at once. In this case, a KID should not be associated with the URL. Instead, the payee should designate a fixed range of customer ID/KID numbers from which Nets can assign to each payer at the time of onboarding.

For example, a generic onboarding URL https://pvu.nets.no/c/1234abcd may be pre-configured with the following data:

{
  "returnUrl": "https://www.payeepage.com/thank-you",
  "purpose": "Monthly membership",
  "storeDebtor": true,
  "supplementDebtorData": true,
  "campaignId": "Online ad 1",
  "amount": "200",
}

This URL can be included as a link in an online ad or a print ad (optionally as a QR code).When a user clicks the ad, they will be taken to the AvtaleGiro onboarding solution E-Agreement, where a customer ID/KID number will be assigned, they will be identified with BankID and personal information will be fetched from the Norwegian population register, an AvtaleGiro will be created, and the new customer can be fetched by the payee.

Base URLs for Link Generator API

Request a link:

POST <<Base URL>>/v1/shorturl

Testing

In the test environment, the API field companyAccountNo should have value 11110500019.

When authenticating with BankID in the test environment, the test users published at https://www.nets.eu/developer/e-ident/eids/Pages/testusers.aspx or https://developer.signicat.com/enterprise/identity-methods/norwegian-bankid.html#test-information may be used. 

API Authentication

Before you can use the AvtaleGiro Onboarding APIs, you must go through an onboarding process.

You will receive two keys, one set for Test and another set for Production access, which are the pairs of unique identifiers called Client ID and Client Secret. The Client Secret should not be shared with anyone.

The two keys will be needed to authenticate your application to the respective environments.

You need access tokens to invoke the API’s resources. Access tokens are passed in the HTTP header when invoking the API. The authorization server provides a Token Endpoint that you can use to generate or renew your access token. The response of the Token Endpoint is a JSON message. You extract the token from the JSON and pass it with an HTTP Authorization header to access the API.

OAuth 2.0

OAuth 2.0 is an industry-standard protocol for authorization. Read more at The OAuth 2.0 Authorization Framework, https://tools.ietf.org/html/rfc6749

The AvtaleGiro Onboarding APIs currently support OAuth 2.0 Specification with confidential client type. A confidential client can maintain the confidentiality of its credentials provided by an authorization server.

OAuth 2.0 defines four roles:

Resource owner: An entity capable of granting access to a protected resource.

Resource server: The server hosting protected resources, capable of accepting and responding to protected resource requests using access tokens.

Client: An application making protected resource requests on behalf of the resource owner and with its authorization.

Authorization server: The server issuing access tokens to the client after successfully authenticating the resource owner obtaining authorization.

At a very high-level, it is possible to break the full OAuth flow into two parts:

• Get a token from the authorization server.

• Use the token to access the resource server.

OAuth 2.0 defines a concept called "authorization grant" which is a credential representing the resource owner's authorization (to access its protected resources) used by the client to obtain an access token. The AvtaleGiro Onboarding API supports Client Credentials grant type.

Authorization server

Base URL’s for Authorization server:

Token end-point

POST: <<Base URL>>/token

Generate access token using Client Credential grant type

1. Obtain a valid client_id and client_secret.

2. Combine the pair in the format client_id:client_secret and encode the combined string using base64. See Encode to Base64 format, https://www.base64encode.org/

3. Use the following sample cURL command to obtain the access token.

Sample cURL:

$ curl -k -d "grant_type=client_credentials"

-H "Authorization: Basic <Base64 encoded client_id:client_secret>"

-H 'Content-Type: application/x-www-form-urlencoded'

https://api-gateway.nets.eu/token

Request Headers

Header Name Value

Content-Type

application/x-www-form-urlencoded

grant_type

client_credentials

Sample response

"access_token": "9e086221-040c-320d-a0fc-4de141718503",
"scope": "am_application_scope default",
"token_type": "Bearer",
"expires_in": 3600

NOTE: Each token is valid for one hour and can be used for subsequent API access.