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:
Note: pvu.nets.no mentioned in the diagram above is now replaced with pvu.avtalegiro.no
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.avtalegiro.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.avtalegiro.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.
Note: pvu.nets.no mentioned in the diagram above is now replaced with pvu.avtalegiro.no
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.avtalegiro.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).
Note: pvu.nets.no mentioned in the diagram above is now replaced with pvu.avtalegiro.no
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.avtalegiro.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.
Note: pvu.nets.no mentioned in the diagram above is now replaced with pvu.avtalegiro.no
Base URLs for Link Generator API
Production
|
https://payments.mastercard.no/creditor-campaign-ondemand
|
Customer test |
https://mtf.payments.mastercard.no/creditor-campaign-ondemand
|
Request a link:
POST <<Base URL>>/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
We use mTLS (Mutual Transport Layer Security) which is certificate based authentication.