README

A Vipps Suite plugin for CraftCMS. Supports recurring subscription agreements and one-time payments without requiring Craft Commerce.

Installation

Install via Composer:

composer require 99x/craft-vipps-suite

Then install the plugin in Craft:

./craft plugin/install vipps-suite

Configuration

1. Navigate to Settings > Plugins > Vipps Suite in the Craft CMS Control Panel
2. Configure the following credentials (preferably using environment variables):
   • Client ID: $VIPPS_CLIENT_ID
   • Client Secret: $VIPPS_CLIENT_SECRET
   • Merchant Serial Number (MSN): $VIPPS_MERCHANT_SERIAL_NUMBER
   • Subscription Key (Primary): $VIPPS_SUBSCRIPTION_KEY_PRIMARY
   • Subscription Key (Secondary): $VIPPS_SUBSCRIPTION_KEY_SECONDARY

Environment Variables

Add these to your .env file:

# Required - OAuth credentials
VIPPS_CLIENT_ID=your_client_id_here
VIPPS_CLIENT_SECRET=your_client_secret_here

# Required - Merchant Serial Number
VIPPS_MERCHANT_SERIAL_NUMBER=your_msn_here

# Required - Subscription API keys
VIPPS_SUBSCRIPTION_KEY_PRIMARY=your_primary_key_here
VIPPS_SUBSCRIPTION_KEY_SECONDARY=your_secondary_key_here

# Optional - Vipps API base URL (defaults to production)
VIPPS_BASE_URL=https://api.vipps.no

# Optional - System information for Vipps API headers
VIPPS_SYSTEM_NAME=Craft CMS
VIPPS_SYSTEM_VERSION=4.14.15
VIPPS_SYSTEM_PLUGIN_NAME=Vipps Suite
VIPPS_SYSTEM_PLUGIN_VERSION=1.0.0

Docker / DDEV Development Setup

# Run code quality checks
ddev composer test

# Fix code style issues
ddev composer fix-cs

# Run PHPStan only
ddev composer phpstan

# Run ECS only
ddev composer check-cs

Requirements

Current Environment:

• Craft CMS 4.14.0 or later
• PHP 8.0.2 or later
• MySQL 8.0.32 or later

Target Compatibility:

• Craft CMS 5.x (code is written to be forward-compatible)
• PHP 8.2+ (code is written to be forward-compatible)
• MySQL 8.x (already compatible)

Additional Requirements:

• Vipps merchant account
• Vipps API credentials (Client ID, Client Secret, Subscription Keys, MSN)

Note: While the plugin is developed on Craft CMS 4 and PHP 8.0.2, all code is written to be compatible with Craft CMS 5 and PHP 8.2 to ensure smooth future upgrades. See Forward Compatibility Guidelines for details.

Getting Vipps Credentials

1. Sign up for a Vipps merchant account
2. Access the Vipps Developer Portal
3. Create an application to get OAuth credentials (Client ID and Client Secret)
4. Obtain Subscription API keys (Primary and Secondary)
5. Get your Merchant Serial Number (MSN) from the Vipps MobilePay business portal

Vipps Login Setup

The plugin includes a complete Vipps Login integration that allows users to authenticate using their Vipps account.

Using Vipps Suite in Templates

The plugin provides a global Twig variable vippsSuite that you can use in any template:

Vipps Login:

{# Simple login link with default redirects #}
<a href="{{ vippsSuite.loginUrl() }}">Login with Vipps</a>

{# Login link with custom redirect URLs #}
<a href="{{ vippsSuite.loginUrl('/', '/?login=failed') }}">
    Login with Vipps
</a>

{# Conditional display based on login status #}
{% if currentUser is null %}
    <a href="{{ vippsSuite.loginUrl('/', '/?login=failed') }}">
        Login with Vipps
    </a>
{% else %}
    <a href="{{ url('/logout') }}">Logout</a>
{% endif %}

Agreement Templates:

{# Link to agreement templates page #}
<a href="{{ vippsSuite.agreementTemplatesUrl() }}">View Agreement Templates</a>

{# With custom redirect URLs #}
<a href="{{ vippsSuite.agreementTemplatesUrl('/', '/?agreement=failed') }}">
    View Agreement Templates
</a>

Check Active Agreement:

{# Check if current user has an active agreement #}
{% if vippsSuite.hasActiveAgreement() %}
    <p>You have an active agreement!</p>
    {# Show agreement content #}
{% else %}
    <p>You don't have an active agreement.</p>
    <a href="{{ vippsSuite.agreementTemplatesUrl() }}">View Templates</a>
{% endif %}

{# Combine with user check #}
{% if currentUser and vippsSuite.hasActiveAgreement() %}
    {# Show premium content #}
{% endif %}

Donations:

{# Link to donations page #}
<a href="{{ vippsSuite.donationsUrl() }}">Make a Donation</a>

Unified Form:

{# Link to unified form page (supports both agreements and payments) #}
<a href="{{ vippsSuite.unifiedFormPageUrl() }}">Become a Donor</a>

{# Form submission URL #}
<form action="{{ vippsSuite.unifiedFormUrl() }}" method="post">
    {{ csrfInput() }}
    <input type="hidden" name="type" value="agreement">
    <input type="hidden" name="amount" value="10000">
    <button type="submit">Subscribe</button>
</form>

Vipps Login Flow

1. User clicks the login link generated by vippsSuite.loginUrl()
2. User is redirected to Vipps authorization page
3. User authenticates with Vipps
4. Vipps redirects back to your site
5. Plugin automatically creates or links the user account
6. User is logged into Craft CMS
7. User is redirected to the success URL (or error URL if login failed)

Next Steps

After installation and configuration:

1. Configure Vipps Login callback URI in your Vipps portal
2. Add Vipps Login button to your templates using vippsSuite.loginUrl()
3. Create agreement templates in Vipps Suite > Agreement Templates
4. Set up agreement template selection pages
5. Configure webhook endpoints for agreement callbacks
6. Set up charge scheduling for recurring payments

For detailed information, see the Product Context and Technical Context documentation.