​Request payer onboarding links via API

The Link Generator for Onboarding Payers to AvtaleGiro provides a payee with short onboarding URLs which can be shared with payers.

visual-overview.png


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:


Input fields


Input Required in request for short URL​ ​Required in AvtaleGiro onboarding (payer’s session) ​Allowed values Description​
requestId​
Yes​ ​n/a ​UUID (Header parameter)
A unique identifier for a request.
companyAccountNo​ ​Yes ​Yes ​11-digit Norwegian bank account number The recipient account of the payee.​ 11110500019 can be used as a test account in the test environment.
​companyName ​No ​No ​Alphanumeric, min 3 characters The name of the company, as it should be displayed to the user.​
agreementType​ ​Yes ​No ​Fixed value: "ATG" The agreement type for which the payer is registering. Currently, only AvtaleGiro is available.​
recruiterId​ ​No ​No ​String ​The ID of the person responsible for onboarding a payer.
​kid ​No ​Yes ​Numeric string, max 25 characters Customer identifier. Must conform to the KID configuration set in the creditor’s AvtaleGiro agreement. See https://www.mastercardpaymentservices.com/norway_/Pages/Dev/KID.aspx for more information on KID.​
amount​ ​No ​No ​Numeric string with 2 decimal places. Min 1.00, max 1000000.00 ​The monthly amount agreed upon by the payer and payee.
​amountLimit ​No ​No, but recommended ​Positive integer. Min 1, max 1000000 The maximum amount that the customer may be charged via AvtaleGiro within a calendar month. If not submitted, it will default to NOK 10000. The value may be changed by the payer.​
notificationDisabled​ ​No ​No ​Boolean (true/false) Sets the default notification setting, which the payer may change. If true, the payer will NOT receive notification of new AvtaleGiro payment claims.​
returnUrl​ ​No ​No ​Complete web address ​The URL to which the user should be directed after completing or cancelling the AvtaleGiro onboarding process.
campaignId​ No​ ​No ​String ​Payee's internal identifier for an onboarding campaign.
purpose​ ​No ​No ​String ​The purpose of the payment.
​storeDebtor ​No ​No ​Boolean (true/false). Note: If supplementDebtorData is true, storeDebtor will be automatically set to true. ​If true, the payer’s information is stored for the payee to fetch via API. See "Fetching new customer data" below for more details.
supplementDebtorData​ ​No ​No ​Boolean (true/false). Note: If supplementDebtorData is true, storeDebtor will be automatically set to true.​ ​If true, information on the customer will be supplemented. Supplemental information will include name at a minimum. If the payer allows, address, phone number, and email address will also be included. Supplemental information is fetched by default from the Norwegian population register, but the user may override this data.
​taxDeductible ​No ​No ​Boolean (true/false) ​If payments are tax deductible for the payer, this parameter should be set to true, and the payer will have the option of sharing his/her social security number with the payee for this purpose.
​freeField1 ​No ​No String Free text field which is stored as part of the payer record for the payee to fetch via API.
​freeField2 ​No ​No String Free text field which is stored as part of the payer record for the payee to fetch via API.
​freeField3 ​No ​No String Free text field which is stored as part of the payer record for the payee to fetch via API.


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.

Visual - use case 1 - simple onboarding.png


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).

Visual - use case 2 - face-to-face.png


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.


Visual - use case 3 - Print or online ad.PNG




Base URLs for Link Generator API


​Production
https://api-gateway.nets.eu/creditor-campaignondemand
​​Pre-production https://api-gateway-pp.nets.eu/creditorcampaign- ondemand-kp​
Test / Customer test​ ​https://api-gateway-pp.nets.eu/creditorcampaign- ondemand-kt

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:

​Production
https://api-gateway.nets.eu
​​Pre-production and test https://api-gateway-pp.nets.eu


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

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.



{
  "error": null,
  "ribbons": [
    {
      "id": "ctl00_PlaceHolderMain_RibbonPanel10_wrapper",
      "color": "#141413",
      "image": "/SiteCollectionImages/background/mastercard_1920x600_brandcircle_connections.png",
      "overlay_alpha": null
    },
    {
      "id": "ctl00_PlaceHolderMain_RibbonPanel11_wrapper",
      "color": "#ffffff",
      "image": null,
      "overlay_alpha": null
    }
  ]
}